| name | main-router |
| description | Intelligent skill router that analyzes user requests and automatically dispatches to the most appropriate skill(s) or zen-mcp tools. Routes to zen-chat for Q&A, zen-thinkdeep for deep problem investigation, codex-code-reviewer for code quality, simple-gemini for standard docs/tests, deep-gemini for deep analysis, or plan-down for planning. Use this skill proactively to interpret all user requests and determine the optimal execution path. |
Main Router - Intelligent Skill Routing Scheduler
Overview
This skill serves as the central intelligence hub that analyzes user requests and automatically routes them to the most appropriate skill(s) for execution. It acts as a smart dispatcher, understanding user intent and orchestrating the right tools for the job.
Core Capabilities:
- Standards-based routing (follows CLAUDE.md)
- Intent analysis and classification
- Skill matching and selection
- Multi-skill orchestration (sequential or parallel)
- Conflict resolution and disambiguation
- Automatic routing without user intervention
- Full automation mode support (router makes decisions autonomously)
Division of Responsibilities:
- Main Router: Analyzes request → Reads standards → Determines skill(s) → Invokes skill(s) → Coordinates execution
- Specialized Skills: Execute their specific tasks when invoked by router
Standards Compliance:
- MUST read global and project CLAUDE.md before routing
- Apply standards hierarchy: Global CLAUDE.md > Project CLAUDE.md
- All routing decisions must align with documented rules and workflows
Active Task Monitoring (CRITICAL - Router Must Not Be Lazy):
Main Router MUST actively monitor the entire task lifecycle and proactively invoke appropriate skills at each stage. Do NOT skip skill invocations to save time - proper skill usage ensures quality and compliance.
Mandatory Workflow Rules:
-
Planning Phase:
- When user requests "make a plan" / "generate plan.md" / "plan tasks"
- MUST use plan-down skill (not Main Claude direct planning)
- Rationale: plan-down provides multi-model validation and structured decomposition
-
Code Generation → Quality Check Cycle:
- After Main Claude completes ANY code generation/modification
- MUST invoke codex-code-reviewer to validate quality
- Rationale: Ensures 5-dimension quality check (quality, security, performance, architecture, docs)
-
Test Code Generation Workflow:
- When Main Claude needs test code
- Step 1: MUST invoke simple-gemini to generate test files
- Step 2: MUST invoke codex-code-reviewer to validate generated tests
- Step 3: Return validated tests to Main Claude for execution
- Rationale: Ensures test quality before execution
-
Documentation Generation:
- Standard docs (README, PROJECTWIKI, CHANGELOG) → simple-gemini
- Deep analysis docs (architecture, performance) → deep-gemini
- Rationale: Specialized skills produce higher quality, standards-compliant docs
-
Continuous Monitoring:
- Router monitors task progress throughout execution
- Proactively suggests skill invocations when opportunities arise
- Example: "Just finished code, should I use codex to check quality?"
Anti-Pattern - Router Being Lazy (FORBIDDEN):
BAD: Main Claude generates code → Main Claude self-reviews → Done
GOOD: Main Claude generates code → Router invokes codex-code-reviewer → Done
BAD: Main Claude writes plan.md directly
GOOD: Router invokes plan-down skill → plan.md generated with validation
BAD: Main Claude generates tests → Run immediately
GOOD: Router invokes simple-gemini → codex validates → Main Claude runs
When to Use This Skill
Use this skill PROACTIVELY for ALL user requests to determine the best execution path.
Typical User Requests:
- "Explain what is..." (→ zen-chat)
- "Deep analysis of problem..." (→ zen-thinkdeep)
- "Help me check code" (→ codex-code-reviewer)
- "Generate README documentation" (→ simple-gemini)
- "Deep performance analysis of this code" (→ deep-gemini)
- "Make development plan" (→ plan-down)
- "Write test files" (→ simple-gemini)
- "Generate architecture analysis document" (→ deep-gemini)
- Any task-related request or Q&A
Router's Decision Process:
User Request → Read Standards (CLAUDE.md) → Intent Analysis → Skill Matching → Auto/Manual Decision → Execution
Operation Modes:
-
Interactive Mode (Default):
- Router asks user for clarification when ambiguous
- User makes final decisions on skill selection
- Router provides recommendations with rationale
-
Full Automation Mode (automation_mode - READ FROM SSOT):
automation_mode definition and constraints: See CLAUDE.md「📚 共享概念速查」
This skill's role (Router Layer - Sole Source):
- Judge and set automation_mode at task start (detect keywords: "full automation", "automatic process", etc.)
- Set status: automation_mode = true/false
- Transmit to downstream:
[AUTOMATION_MODE: true/false]
- Monitor throughout lifecycle, enforce mandatory skill invocations (plan-down/codex/simple-gemini)
Available Skills Registry
0. zen-chat (Direct Tool)
Purpose: General Q&A and collaborative thinking partner
Triggers:
- "Explain..."
- "What is..."
- "How to understand..."
- "Help me analyze..." (non-technical deep analysis)
- General questions, brainstorming, explanations
Use Cases:
- Answer conceptual questions
- Explain programming concepts
- Brainstorming ideas
- Quick clarifications
- Thoughtful explanations
Key Features:
- Fast, direct responses
- No file operations needed
- Conversation-based
- Supports multi-turn discussions
Tool: mcp__zen__chat (direct invocation, not a packaged skill)
0.5. zen-thinkdeep (Direct Tool)
Purpose: Multi-stage investigation and reasoning for complex problem analysis
Triggers:
- "Deep analysis of problem..."
- "Investigate root cause of this bug..."
- "Systematic analysis..." (technical deep dive)
- "Complex problem analysis..."
- Architecture decisions, complex bugs, performance challenges
Use Cases:
- Complex bug investigation
- Architecture decision analysis
- Performance bottleneck deep dive
- Security analysis
- Systematic hypothesis testing
Key Features:
- Multi-stage investigation workflow
- Hypothesis-driven analysis
- Evidence-based findings
- Expert validation
- Comprehensive problem-solving
Tool: mcp__zen__thinkdeep (direct invocation, not a packaged skill)
1. codex-code-reviewer
Purpose: Code quality review with iterative fix-and-recheck cycles
Triggers:
- "Use codex to check code"
- "Check if the just-generated code has problems"
- "Check code after every generation"
- "Code review"
- "Code quality check"
Use Cases:
- Post-development code quality validation
- Pre-commit code review
- Bug fix verification
- Refactoring quality assurance
Key Features:
- 5-dimension quality check (quality, security, performance, architecture, documentation)
- Iterative fix cycles (max 5 iterations)
- User approval required before fixes
- Based on CLAUDE.md standards
Tool: mcp__zen__codereview
2. simple-gemini
Purpose: Standard documentation and test code generation
Triggers:
- "Use gemini to write test files"
- "Use gemini to write documentation"
- "Generate README"
- "Generate PROJECTWIKI"
- "Generate CHANGELOG"
- "Write test code"
Use Cases:
- Generate standard project documentation (PROJECTWIKI, README, CHANGELOG, ADR)
- Write test code files
- Create project templates
- Standard documentation maintenance
Key Features:
- Two modes: Interactive (default) and Automated
- Document types: PROJECTWIKI, README, CHANGELOG, ADR, plan.md
- Test code generation with codex validation
- Follows CLAUDE.md standards
Tool: mcp__zen__clink (launches gemini CLI in WSL)
3. deep-gemini
Purpose: Deep technical analysis documents with complexity evaluation
Triggers:
- "Use gemini for deep code logic analysis"
- "Generate architecture analysis document"
- "Analyze performance bottlenecks and generate report"
- "Deep understanding of this code and generate documentation"
- "Generate model architecture analysis"
Use Cases:
- Code logic deep dive
- Model architecture analysis
- Performance bottleneck analysis
- Technical debt assessment
- Security analysis report
Key Features:
- Two-stage workflow: clink (Gemini CLI analysis) → docgen (dual-phase document generation)
- Big O complexity analysis included (docgen core capability)
- Automatic Mermaid diagram generation
- Evidence-based findings
- Professional technical writing
Tools: mcp__zen__clink + mcp__zen__docgen
docgen workflow:
- Step 1: Exploration (explore project structure, formulate documentation plan)
- Step 2+: Per-File Documentation (generate structured docs with complexity analysis)
4. plan-down ⭐ MANDATORY for Planning
Purpose: Intelligent planning with task decomposition and multi-model validation
CRITICAL: This skill is MANDATORY for all plan.md generation tasks
- Main Claude must NOT generate plan.md directly
- Router MUST invoke plan-down for all planning requests
- Rationale: Ensures multi-model validation and structured decomposition
Triggers:
- "Help me make a plan"
- "Generate plan.md"
- "Use planner for task planning"
- "Help me break down tasks"
- "Make implementation plan"
- "Plan the project"
Use Cases:
- Feature development planning
- Project implementation roadmaps
- Refactoring strategies
- Migration plans
- Complex task breakdown
Key Features:
- Two-stage workflow: planner (decomposition) → consensus (validation)
- Multi-model evaluation (codex, gemini, gpt-5)
- Standards-based planning (CLAUDE.md)
- Mermaid dependency graphs
- Risk assessment tables
Tools: mcp__zen__chat (Phase 0 method clarity judgment) + mcp__zen__planner + mcp__zen__consensus (conditional - only for Automatic + Unclear path) + mcp__zen__clink (when using consensus with codex/gemini)
Model Support (G10 Compliance - CRITICAL):
- codex/gemini: MUST use
mcp__zen__clink to establish CLI session first (otherwise 401 error)
- Other models: Direct API access
- Detailed standards: See
references/standards/cli_env_g10.md
Enforcement:
IF user requests planning OR plan.md generation:
MUST route to plan-down
NEVER allow Main Claude to create plan.md directly
Reason: plan-down provides superior planning quality through:
- Multi-stage interactive planning
- Multi-model consensus validation
- Standards compliance verification
- Risk assessment and dependency analysis
5. gemini-frontend ⭐ MANDATORY for Frontend/Mobile Development
Purpose: Frontend and mobile development specialist using Gemini CLI with multimodal capabilities
适用场景：
- React/Vue/Angular 组件开发
- React Native/Flutter 移动端开发
- 设计稿 → 前端代码实现（multimodal）
- UI/UX 实现和优化
- 前端项目重构
Triggers:
- "Help me build a React component"
- "Generate Vue/Angular code"
- "Convert this design to code" (with image)
- "Implement this UI feature"
- "Mobile app development" (React Native/Flutter)
- Keywords: React, Vue, Angular, component, 组件, 页面, UI, 前端, mobile, Flutter
Core Advantages (Based on Gemini 3.0):
- 📷 Multimodal Capability: Directly understand design mockups and UI screenshots
- 📚 Ultra-long Context: 1M tokens, handles large monorepos
- 🎨 UI Understanding: PhD-level reasoning for complex UI logic
- 🚀 Code Generation: Excels at React/Vue/Flutter code generation
Use Cases:
- Design-to-code conversion
- Component library development
- Mobile UI implementation
- Frontend architecture setup
- State management implementation
Key Features:
- 5-phase workflow (Init → Analysis → Generation → Quality Check → Documentation)
- Dual quality validation (codereview + clink CLI) - complies with G8
- Mermaid diagram updates - complies with G4
- Environment-adaptive CLI calls - complies with G10
- Inherits
automation_mode and coverage_target from router
Tools: mcp__zen__clink (gemini CLI) + mcp__zen__codereview + simple-gemini
Frontend Detection Scoring:
- Tier 1 Keywords (+30-35 points): React, Vue, Angular, component, 组件, 页面, UI, 前端
- Tier 2 Keywords (+15-20 points): Flutter, React Native, mobile, 移动端, iOS, Android
- Tier 3 Context (+10 points): package.json exists with frontend dependencies
- Image Attachment (+25 points): Design mockups, UI screenshots
- Backend Signal Penalty (-15 to -25 points): API, backend, database, FastAPI, Django
Routing Thresholds:
- Score ≥ 80: Auto-route to gemini-frontend
- Score 50-79: Ask user confirmation
- Score < 50 AND backend_signals ≥ 2: Fullstack project, suggest task decomposition
Enforcement:
IF frontend_score ≥ 80:
Auto-route to gemini-frontend (high confidence)
IF 50 ≤ frontend_score < 80:
Ask user: "检测到前端开发需求，是否使用 gemini-frontend?"
IF frontend_score < 50 AND backend_signals ≥ 2:
Notify user: "检测到全栈项目，建议任务分解：
- 前端部分 → gemini-frontend
- 后端部分 → codex-code-reviewer 或其他技能"
Detailed Examples:
Routing Decision Logic
Phase 0: Standards Reading & MCP Discovery (CRITICAL - First Step)
Main Router's Action:
Before ANY routing decision, MUST complete the following two sub-phases:
Phase 0.1: Read Standards
Read the following files to understand project-specific rules and workflows:
a) Read Global Standards:
- Global CLAUDE.md:
/home/vc/.claude/CLAUDE.md
- Extract: Global rules (G1-G11), phase requirements (P1-P4), routing mechanism, core principles
- Key focus: Which phase user is in, execution permissions, documentation requirements
- Extract: Model development workflow, ethics principles, reproducibility requirements
b) Read Project-Specific Standards (if exist):
- Project CLAUDE.md:
./CLAUDE.md (current directory)
- Extract: Project-specific rules, custom workflows, overrides
Standards Priority Hierarchy (when conflicts):
- Global CLAUDE.md (highest priority)
- Project CLAUDE.md (overrides global)
- PROJECTWIKI.md (lowest priority)
Phase 0.2: 动态 MCP 发现与智能适配（Dynamic MCP Discovery & Adaptation）
核心原则：不假设任何 MCP 工具"一定存在"，运行时动态检测并智能适配。
MCP 环境扫描策略
检测时机：
- 会话启动时：首次路由前执行快速扫描（可选，推荐）
- 运行时检测：技能调用 MCP 工具时懒加载检测（默认）
- 失败触发：MCP 调用失败时重新扫描并更新缓存
检测方法：
mcp_capabilities = {}
def detect_mcp_availability():
"""运行时检测 MCP 工具可用性"""
try:
version_info = call_tool("mcp__zen__version")
mcp_capabilities["zen-mcp"] = {
"available": True,
"version": version_info.get("version"),
"tools": extract_available_tools(version_info)
}
except Exception:
mcp_capabilities["zen-mcp"] = {"available": False}
try:
config = call_tool("mcp__serena__get_current_config")
mcp_capabilities["serena-mcp"] = {
"available": True,
"tools": list_serena_tools()
}
except Exception:
mcp_capabilities["serena-mcp"] = {"available": False}
try:
search_test = call_tool("mcp__unifuncs__web-search", {"query": "test", "count": 1})
mcp_capabilities["unifuncs-mcp"] = {"available": True}
except Exception:
mcp_capabilities["unifuncs-mcp"] = {"available": False}
return mcp_capabilities
技能 → MCP 依赖关系（动态映射）
技能与 MCP 工具的依赖分为三类：
- 必需工具（Required）：技能核心功能依赖，缺失则无法工作
- 增强工具（Enhancement）：提升技能能力，缺失可降级
- 可选工具（Optional）：锦上添花，缺失无影响
动态依赖映射表：
| Skill | 必需工具 | 增强工具 | 降级方案 |
|---|
| zen-chat | mcp__zen__chat | mcp__zen__apilookup
mcp__unifuncs__web-search | 降级到主模型直接回答（无多轮协作） |
| zen-thinkdeep | mcp__zen__thinkdeep | mcp__serena__* (代码分析)
mcp__zen__debug | 降级到主模型单轮深度分析 |
| codex-code-reviewer | mcp__zen__codereview
或 mcp__zen__clink (codex CLI) | mcp__serena__* (符号编辑)
mcp__zen__precommit | 使用主模型 + Read/Edit 工具进行审查 |
| simple-gemini | mcp__zen__clink (gemini CLI) | mcp__serena__* (代码读取)
mcp__unifuncs__web-reader | 降级到主模型直接生成文档/测试 |
| deep-gemini | mcp__zen__clink (gemini CLI)
mcp__zen__docgen | mcp__serena__* (代码分析)
mcp__zen__apilookup | 降级到主模型深度分析 |
| plan-down | mcp__zen__chat (方法判断)
mcp__zen__planner (任务分解) | mcp__zen__consensus (自动化模式)
mcp__serena__read_memory (项目上下文)
mcp__zen__clink (codex/gemini CLI) | 降级到主模型直接规划 |
| gemini-frontend | mcp__zen__clink (gemini CLI) | mcp__serena__* (代码分析)
mcp__unifuncs__web-reader (设计参考) | 降级到主模型前端开发 |
G10 合规特殊要求：
- 使用 codex/gemini 模型时，必须先用
mcp__zen__clink 建立 CLI 会话
- plan-down 的四路径工作流：Phase 0 使用 chat 判断方法清晰度，Automatic + Unclear 路径需要 consensus
智能适配与降级策略
适配原则：
-
用户显式指定 MCP 工具时：
- 优先尝试用户指定的工具
- 如果工具不可用，通知用户并提供替代方案
- 示例：用户说 "use serena to analyze code" → 检测 serena → 不可用则通知
-
Router 自动选择技能时：
- 根据 MCP 可用性调整技能推荐优先级
- 必需工具不可用 → 降级到备用方案
- 仅增强工具不可用 → 静默降级，不通知用户
-
降级决策树：
IF 技能必需工具全部可用:
→ 正常路由到该技能（最优方案）
ELSE IF 技能必需工具部分缺失:
→ 检查降级方案是否可行
IF 降级方案可行:
→ 使用降级方案（通知用户，如果是显式请求）
ELSE:
→ 通知用户工具缺失，请求确认或提供替代方案
ELSE IF 仅增强工具缺失:
→ 正常路由，静默降级（不通知用户）
降级方案示例：
| 原方案 | 缺失工具 | 降级方案 | 通知用户？ |
|---|
| codex-code-reviewer | zen-mcp 完全不可用 | 主模型 + Read/Edit 工具审查 | ✅ 是（显著功能降级） |
| simple-gemini | clink 不可用 | 主模型直接生成文档 | ✅ 是（质量可能下降） |
| zen-chat | zen__apilookup 不可用 | 仅使用 zen__chat，无 API 查询 | ❌ 否（增强功能，非必需） |
| zen-thinkdeep | serena 不可用 | 使用 Read/Grep 工具代替代码分析 | ❌ 否（自动适配） |
运行时适配示例
示例 1：用户显式请求使用 codex
用户："use codex to check the code"
Router 执行：
1. 检测 zen-mcp 可用性
- IF zen-mcp 可用 → 路由到 codex-code-reviewer（使用 mcp__zen__codereview）
- IF zen-mcp 不可用但 clink 可用 → 路由到 codex-code-reviewer（使用 mcp__zen__clink + codex CLI）
- IF 两者都不可用 → 通知用户：
"检测到 zen-mcp 和 clink 均不可用。可以使用主模型进行代码审查（功能受限），是否继续？"
示例 2：Router 自动路由到 simple-gemini
Router 判断：需要生成 README 文档 → 路由到 simple-gemini
适配流程：
1. 检测 mcp__zen__clink 可用性
- IF 可用 → 正常调用 simple-gemini（使用 gemini CLI）
- IF 不可用 → 降级到主模型直接生成（通知用户："gemini CLI 不可用，使用主模型生成文档"）
2. 检测增强工具（serena, unifuncs）
- IF serena 可用 → 增强代码读取能力
- IF serena 不可用 → 使用 Read 工具（静默降级，不通知）
示例 3：全自动化模式下的 plan-down
Router 判断：P2 阶段，需要生成 plan.md → 路由到 plan-down
适配流程：
1. 检测必需工具（chat, planner）
- IF 全部可用 → 继续
- IF 任一缺失 → 降级到主模型直接规划（通知："plan-down 依赖工具缺失，使用主模型规划"）
2. 检测增强工具（consensus, clink）
- IF automation_mode=true 且方法模糊 → 需要 consensus
- consensus 可用 → 正常多模型验证
- consensus 不可用 → 降级到单模型规划（通知："多模型验证不可用，使用单模型规划"）
- IF consensus 需要 codex/gemini → 检测 clink
- clink 可用 → 符合 G10，建立 CLI 会话
- clink 不可用 → 跳过 consensus（静默降级）
MCP 可用性缓存与刷新
缓存策略：
- 会话级缓存：检测结果在同一会话中共享
- 失败触发刷新：MCP 调用失败时自动重新检测
- 手动刷新：用户可请求 "refresh MCP status" 强制重新扫描
缓存数据结构：
mcp_status_cache = {
"zen-mcp": {
"available": True,
"last_check": "2025-11-19T11:30:00Z",
"tools": ["chat", "thinkdeep", "codereview", "clink", "planner", ...]
},
"serena-mcp": {
"available": True,
"last_check": "2025-11-19T11:30:00Z",
"tools": ["list_dir", "find_file", "search_for_pattern", ...]
},
"unifuncs-mcp": {
"available": False,
"last_check": "2025-11-19T11:30:00Z",
"error": "Connection refused"
}
}
Standards-Based Routing Rules（基于标准的路由规则）
根据 CLAUDE.md 阶段和 MCP 可用性动态调整路由：
- P1 (分析问题) → 优先 zen-thinkdeep（如可用），否则主模型分析
- P2 (制定方案) → 优先 plan-down（如可用），否则主模型规划
- P3 (执行方案) → 代码完成后强制 codex-code-reviewer（如可用），否则主模型审查
- automation_mode=true → 优先使用 MCP 增强的自动化工作流
- 文档生成需求 → 优先 simple-gemini/deep-gemini（如 clink 可用），否则主模型生成
- G3 违规（禁止执行） → 不路由到任何执行相关技能
透明通知原则：
- 关键功能降级（必需工具缺失） → 必须通知用户
- 增强功能降级（可选工具缺失） → 静默适配，不通知
- 用户显式请求的工具缺失 → 必须通知并提供替代方案
Phase 0.3: Set Coverage Target (G9 Compliance)
coverage_target definition and constraints: See CLAUDE.md「📚 共享概念速查」
This skill's role (Router Layer - Sole Setting Source):
- Ask user in P1/P2 phase (or use default 85%)
- Inquiry script: "Suggest 85%, minimum 70%. Default 85% if unsure."
- Transmit to downstream:
[COVERAGE_TARGET: X%]
- Record to plan.md (acceptance criteria)
Fixed Routing Rules (MANDATORY - Auto-Trigger)
These rules MUST be applied automatically at specific workflow points:
Rule 1: plan.md Generation → plan-down (MANDATORY)
- Trigger: User requests "make a plan" / "generate plan.md" / "plan tasks"
- Action: MUST use plan-down skill, FORBIDDEN for main model to write plan.md directly
- Reason: plan-down provides multi-model validation, structured decomposition, standards compliance
Rule 2: Code Completed → codex-code-reviewer (MANDATORY)
- Trigger: Main model completes any code generation or modification
- Action: MUST use codex-code-reviewer for 5-dimension quality check (quality, security, performance, architecture, documentation)
- Reason: Ensure code quality meets standards
Rule 3: Test Code Needed → Workflow (MANDATORY)
- Trigger: Need to generate test code
- Action:
- Step 1: Use simple-gemini to generate test files (pass
[COVERAGE_TARGET: X%])
- Step 2: Use codex-code-reviewer to validate test code quality (pass
[COVERAGE_TARGET: X%])
- Step 3: Main model executes tests
- Reason: Ensure test code itself is correct and high-quality
Rule 4: Documentation Needed → Skill-Based (MANDATORY)
- Trigger: Need to generate/update documentation
- Action:
- Standard docs (README, PROJECTWIKI, CHANGELOG): Use simple-gemini
- Deep analysis docs (architecture, performance): Use deep-gemini
- Reason: Specialized skills produce higher quality, standards-compliant documents
Rule 5: P3 Code Changes → Document Linkage (MANDATORY)
- Trigger: Code changes in P3 (Execute Solution) phase
- Action:
- Update PROJECTWIKI.md (affected modules/interfaces/flows)
- Update CHANGELOG.md (new entry with commit SHA)
- Establish bidirectional links (PROJECTWIKI ↔ CHANGELOG)
- Reason: G1 compliance (documentation first-class citizen)
Rule 6: P4 Error Fixed → Regression Gate (MANDATORY)
- Trigger: P4 (Error Handling) phase completes bug fix
- Action (3-step validation, cannot skip):
- Step 1: Use mcp__zen__codereview for workflow validation
- Step 2: Use mcp__zen__clink (codex CLI) for deep code analysis
- Step 3: Verify document linkage:
- PROJECTWIKI.md updated (design decisions & technical debt section includes defect postmortem)
- CHANGELOG.md updated (Fixed section with repair summary)
- Bidirectional links established
- Reason: G8 compliance (mandatory double-pass validation), prevent hasty fixes
Anti-Lazy Principle:
- Main-router MUST actively monitor task lifecycle
- At each critical node, think: "Should I invoke a skill here?"
- ABSOLUTELY FORBIDDEN: Skip skill invocation to "save effort", letting main model handle tasks that specialized skills should complete
Phase 1: Intent Classification
Main Router's Action:
Analyze the user request to identify:
-
Primary Intent:
- General Q&A / explanations → zen-chat
- Complex problem investigation → zen-thinkdeep
- Code review / quality check → codex-code-reviewer
- Standard documentation → simple-gemini
- Deep technical analysis → deep-gemini
- Planning / task breakdown → plan-down
- Other (direct execution by Main Claude)
-
Request Characteristics:
- Target: What is the subject? (code files, documentation, architecture, plan)
- Action: What needs to be done? (check, generate, analyze, plan)
- Depth: Surface-level or deep analysis?
- Output: What is expected? (report, document, plan, fixed code)
-
Context Signals:
- Keywords in user message
- Recently modified files (git status)
- Existing project state (has plan.md? has PROJECTWIKI.md?)
- User's workflow stage (development, review, planning)
Phase 2: Skill Matching
Decision Tree:
IF user asks general question ("explain", "what is", "how to understand"):
→ zen-chat
ELSE IF user requests deep problem analysis ("deep problem analysis", "investigate bug", "systematic analysis"):
→ zen-thinkdeep
ELSE IF user mentions "codex" OR "code check" OR "code review":
→ codex-code-reviewer
ELSE IF user mentions "gemini" AND ("documentation" OR "test"):
IF mentions "deep" OR "analysis" OR "architecture" OR "performance":
→ deep-gemini
ELSE:
→ simple-gemini
ELSE IF user mentions "planning" OR "plan" OR "roadmap":
→ plan-down
ELSE IF intent is "code review":
→ codex-code-reviewer
ELSE IF intent is "document generation":
IF document type in [README, PROJECTWIKI, CHANGELOG, test]:
→ simple-gemini
ELSE IF analysis type in [architecture, performance, code logic]:
→ deep-gemini
ELSE IF intent is "planning":
→ plan-down
ELSE IF intent is "Q&A" (no code/file operations):
→ zen-chat
ELSE:
→ Main Claude (direct execution, no skill routing)
Confidence Scoring:
For each tool/skill, calculate confidence score (0-100):
confidence_scores = {
"zen-chat": calculate_qa_confidence(request),
"zen-thinkdeep": calculate_deep_investigation_confidence(request),
"codex-code-reviewer": calculate_code_review_confidence(request),
"simple-gemini": calculate_simple_doc_confidence(request),
"deep-gemini": calculate_deep_analysis_confidence(request),
"plan-down": calculate_planning_confidence(request)
}
if max(confidence_scores.values()) >= 60:
selected_tool = max(confidence_scores, key=confidence_scores.get)
else:
ask_user_to_clarify()
if automation_mode_enabled:
if max(confidence_scores.values()) >= 50:
selected_tool = max(confidence_scores, key=confidence_scores.get)
log_auto_decision(selected_tool, confidence_scores)
else:
selected_tool = "main_claude"
Phase 3: Execution Strategy
Single Skill Execution:
User Request → Analyze → Match to Skill X → Invoke Skill X → Return Result
Multi-Skill Execution (Sequential):
Example: "Generate docs then check code"
1. Invoke simple-gemini (generate docs)
2. Wait for completion
3. Invoke codex-code-reviewer (check code)
4. Return combined results
Multi-Skill Execution (Parallel - if independent):
Example: "Generate plan and README simultaneously"
1. Invoke plan-down in parallel
2. Invoke simple-gemini in parallel
3. Wait for both to complete
4. Return combined results
Phase 4: Disambiguation
When multiple skills could apply:
Option 1: Ask User (Interactive Mode)
Detected that your request can use the following skills:
1. simple-gemini - Generate standard documentation
2. deep-gemini - Generate deep analysis documentation
Please choose:
- Enter 1: Use simple-gemini (fast, standardized)
- Enter 2: Use deep-gemini (in-depth, includes complexity analysis)
Option 2: Auto-Select (Full Automation Mode)
CRITICAL: In Full Automation Mode, DO NOT ask user "continue?" or present choices
-
Activation: User explicitly requests "full automation"/"complete automation"/"automated process" in initial request
-
Behavior: Router and Main Claude make ALL decisions without user intervention
-
Forbidden Actions:
- "Continue?" (Yes/No)
- "Please choose..." (Option 1/2/3)
- "Do you need..." (Need/Don't need)
- Any form of asking user for confirmation or choice
-
Correct Actions:
- "[Full Auto Mode] Detected planning needed, auto-invoking plan-down..."
- "[Full Auto Mode] Code generated, auto-invoking codex for quality check..."
- Direct execution with logged rationale
-
Decision Rules:
- Uses confidence scores with lower threshold (≥50 instead of ≥60)
- Prefer simpler skills for ambiguous cases:
- simple-gemini over deep-gemini (unless "deep" mentioned)
- zen-chat over zen-thinkdeep (unless "investigate" or "bug" mentioned)
- Direct execution over complex skills when unclear
- Log all auto-decisions with rationale for transparency
- Standards compliance: Always follows CLAUDE.md rules
-
Exception - Only Ask User When:
- Blocking errors (environment missing, dependency errors)
- Security risks (sensitive data exposure, production operations)
Full Automation Mode Decision Template:
[Full Auto Mode - Auto Decision]
Detected: {task_description}
Auto-selected: {selected_tool}
Confidence: {confidence_score}%
Rationale: {rationale based on standards and intent}
Standards basis: {relevant CLAUDE.md rules}
Starting execution...
Router Workflow: Step-by-Step
Step 1: Receive User Request
Main Router's Action:
User: "Help me check the just-generated code"
Router Internal Analysis:
- Keywords detected: "check", "code"
- Intent: Code review
- Target: Recently generated code
- Expected output: Quality report + fixes
Step 2: Read Standards & Discover MCPs (CRITICAL)
Main Router's Action:
Part A: Standards Reading
Standards Reading:
a) Global CLAUDE.md (/home/vc/.claude/CLAUDE.md):
- G1: Documentation First-Class Citizen - code changes must synchronize doc updates
- G3: No Execution Permission Scenario - requires explicit user consent
- Current phase: P3 (Execute Solution) - just completed code generation
b) Global CLAUDE.md (/home/vc/.claude/CLAUDE.md):
- Code standards: Clear, readable
- Quality threshold: Coverage ≥ 70%
c) Project CLAUDE.md (./CLAUDE.md): [If exists]
- Project-specific rules
d) Project CLAUDE.md (./CLAUDE.md): [If exists]
- Model-specific requirements
Standards-Based Decision:
- P3 phase → Code review recommended after code changes (CLAUDE.md requirement)
- G1 rule → Must check if documentation was updated
- User approval needed before fixes (G3)
Part B: MCP Capability Reference (No Pre-check)
MCP Assumptions:
zen-mcp:
Status: Assumed AVAILABLE (default)
Tools: All 13 zen-mcp tools assumed ready
Strategy: Optimistic routing - verify on actual invocation
User-Mentioned MCPs:
Detection: Check if user explicitly mentioned MCP tools in request
Example triggers: "use serena", "use unifuncs to search", "call mcp__serena__find_symbol"
Status: Assumed AVAILABLE (if mentioned by user)
Strategy: Optimistic routing - honor user's explicit tool choice
Optional Enhancement MCPs:
serena: Can be discovered on-demand for code intelligence
unifuncs: Can be discovered on-demand for web capabilities
Strategy: Lazy discovery - only if needed for enhancement
Routing Decision for codex-code-reviewer:
Required: mcp__zen__codereview (assumed available )
Enhancement: serena tools (optional, will discover if needed)
User preference: None mentioned in this request
→ Decision: Proceed with codex-code-reviewer
Rationale: zen-mcp assumed available, no blocking issues
Step 3: Analyze Intent
Main Router's Action:
Intent Classification:
- Primary Intent: Code review
- Secondary Intent: None
- Complexity: Standard (not deep analysis)
- Urgency: Normal
Context Signals:
- Git status shows modified files: src/features.py, src/model_training.py
- No explicit skill mentioned by user
- Recent activity: Code generation just completed
Standards Alignment:
- Matches P3 phase requirement for post-code-change review
- Aligns with G1 (need to verify doc updates)
Step 4: Match to Skill(s) (Optimistic Routing)
Main Router's Action:
Skill Matching:
- codex-code-reviewer: 95% confidence
- Reason: Intent is code review, has modified files
- Standards support: P3 phase requirement
- zen-mcp: Assumed available (optimistic)
- simple-gemini: 10%
- zen-mcp: Assumed available
- deep-gemini: 15%
- zen-mcp: Assumed available
- plan-down: 5%
- zen-mcp: Assumed available
Decision: Route to codex-code-reviewer
Rationale: Highest confidence + Standards alignment
Note: zen-mcp availability assumed, will verify during execution
Step 5: Invoke Selected Skill (Optimistic Execution)
Main Router's Action:
Invoking: codex-code-reviewer
Parameters:
- Files to review: [src/features.py, src/model_training.py]
- Review type: full
- User approval: required
MCP Strategy:
Primary tools: zen-mcp (assumed available, no pre-check)
Enhancement tools: serena/unifuncs (can discover on-demand if needed)
Execution:
[codex-code-reviewer executes workflow using zen-mcp tools]
Error Handling (if zen-mcp fails):
1. Skill reports error to router
2. Router notifies user: "mcp__zen__codereview currently unavailable"
3. Router suggests fallback: Main Claude direct code review
4. User chooses: Continue with fallback OR troubleshoot MCP
Step 6: Return Results to User
Main Router's Action:
Code review completed (using codex-code-reviewer):
Review results:
- Reviewed files: 2
- Issues found: 3 (fixed)
- Review rounds: 2 / 5
Standards compliance check:
G1: Verified documentation updates (PROJECTWIKI.md, CHANGELOG.md)
G3: User authorization obtained before fixes
Quality threshold: Coverage reached 75% (exceeds 70% threshold)
Detailed report:
[codex-code-reviewer's output]
Routing Examples
Note: For detailed routing examples with comprehensive Chinese descriptions and step-by-step decision processes, please refer to: references/routing_examples.md
Quick Example Index
The routing_examples.md file contains 14 complete examples demonstrating main-router's decision-making process:
- Example 1: General Q&A Request - Simple conceptual questions → zen-chat
- Example 2: Deep Problem Investigation - Complex debugging → zen-thinkdeep
- Example 3: Simple Document Generation - Standard docs → simple-gemini
- Example 4: Code Quality Check - Explicit codex request → codex-code-reviewer
- Example 5: Deep Technical Analysis - Complexity analysis → deep-gemini
- Example 6: Planning Request - Task decomposition → plan-down
- Example 7: Ambiguous Request - Clarification workflow
- Example 8: Multi-Skill Sequential - Multi-task execution
- Example 9: Full Automation Mode - Zero-wait principle demonstration
- Example 10: User Explicitly Mentions MCP Tools - MCP tool routing
- Example 11: Complete Task Lifecycle ⭐ BEST PRACTICE - Active monitoring
- Example 12: Frontend Development Request ⭐ NEW - Frontend detection scoring → gemini-frontend
- Example 13: Fullstack Project Detection ⭐ NEW - Task decomposition for fullstack
- Example 14: Code + Review Workflow - Sequential skill invocation
Quick Reference - Example 1 (General Q&A):
User: "Explain what is overfitting in machine learning?"
Router Decision:
Intent: General Q&A
Keywords: "explain", "what is"
Target: Conceptual explanation
Output: Answer/explanation (no file operations)
→ Route to: zen-chat
Rationale:
- Pure conceptual question
- No file/code operations required
- Fast response with zen-chat is sufficient
- No need for complex analysis workflow
Best Practices
For Effective Routing
-
Active Monitoring (CRITICAL - Anti-Lazy Principle):
- Router MUST monitor task lifecycle continuously
- Proactively invoke skills at appropriate stages
- NEVER allow Main Claude to skip quality checks
- Mandatory interventions:
- plan.md generation → MUST use plan-down
- Code generation complete → MUST use codex-code-reviewer
- Test code needed → MUST use simple-gemini → codex validation
- Documentation needed → MUST use simple-gemini/deep-gemini
- Think: "What skill should be used at this stage?"
-
Keyword Detection:
- Look for explicit skill/tool names (chat, thinkdeep, codex, gemini, planner)
- Look for action verbs (explain, investigate, check, generate, analyze, plan)
- Look for output types (answer, investigation report, documentation, plan, test)
- Look for question patterns (what is, how to understand, why)
-
Context Awareness:
- Check git status for recently modified files
- Check for existing artifacts (plan.md, PROJECTWIKI.md)
- Consider user's recent interactions
- Note project phase (planning, development, review)
-
Confidence Thresholds:
- High confidence (≥80): Auto-route
- Medium confidence (60-79): Auto-route with notification
- Low confidence (<60): Ask user for clarification
-
User Communication:
- Always inform user which skill was selected
- Provide rationale for skill selection
- Allow user to override router's decision
-
Error Handling:
- If selected skill fails, offer fallback options
- If no skill matches, execute directly with Main Claude
- If user request is unclear, ask clarifying questions
Router Communication Template
Format:
[Decision Notification]
Detected task type: [Task Type]
Selected skill: [Skill Name]
Rationale: [Brief explanation]
Starting execution...
Example:
[Decision Notification]
Detected task type: Code quality review
Selected skill: codex-code-reviewer
Rationale: You requested code quality check, codex-code-reviewer provides comprehensive 5-dimensional review
Starting execution...
Routing Decision Matrix
| User Intent | Primary Keywords | Selected Tool/Skill | Rationale |
|---|
| General Q&A | explain, what is, how to understand | zen-chat | General Q&A, no file ops |
| Deep Problem Investigation | deeply analyze problem, investigate bug, systematic analysis | zen-thinkdeep | Multi-stage investigation |
| Code Review | check, review, codex | codex-code-reviewer | Code quality validation |
| Standard Documentation | documentation, README, CHANGELOG, test | simple-gemini | Standard doc templates |
| Deep Technical Analysis | deep, analyze, architecture, performance, complexity | deep-gemini | Technical analysis + complexity |
| Planning | plan, planning, decompose | plan-down | Task decomposition + validation |
| Document Generation (Unclear) | generate document | Ask User | Ambiguous - need clarification |
Special Cases
Case 1: No Matching Skill
Scenario: User request doesn't match any skill
Action:
Router Analysis:
- No skill confidence > 60%
- Request is outside skill scope
→ Decision: Execute directly with Main Claude
→ Notification: "This task will be handled directly by the main model (no specialized skill needed)"
Case 2: Conflicting Skills
Scenario: Multiple skills have similar confidence scores
Action:
Router Analysis:
- simple-gemini: 75%
- deep-gemini: 73%
- Difference < 10% → Ambiguous
→ Decision: Ask user to choose
→ Present both options with pros/cons
Case 3: Runtime MCP Tool Failure
Scenario A: zen-mcp tool fails during skill execution (discovered at runtime)
Action:
Skill Execution Error:
- Skill: deep-gemini
- Failed MCP call: mcp__zen__docgen
- Error: "MCP tool not available" or "Connection failed"
Router Receives Error and Responds:
→ Notification to User:
"Issue encountered while executing deep-gemini:
mcp__zen__docgen is currently unavailable.
Available options:
1. Use simple-gemini (only requires mcp__zen__clink)
2. Main model generates document directly (no MCP enhancement)
3. Check zen-mcp service status and retry
Please choose (or enter 3 and use /mcp status to check)"
User Choice Handling:
- Choice 1 → Route to simple-gemini
- Choice 2 → Main Claude direct execution
- Choice 3 → Wait for user to troubleshoot, then retry
Note: This only happens when zen-mcp actually fails at runtime,
not during routing phase (optimistic assumption).
Scenario B: User-mentioned MCP tool fails at runtime
Action:
Direct MCP Invocation Error:
- User request: "Use serena's find_symbol to analyze code"
- Failed MCP call: mcp__serena__find_symbol
- Error: "MCP server 'serena' not found" or "Tool not available"
Router Receives Error and Responds:
→ Notification to User:
"Your specified MCP tool is currently unavailable:
mcp__serena__find_symbol
Error details: {error_details}
Available options:
1. Use zen-mcp's code analysis tool (mcp__zen__thinkdeep)
2. Main model reads code directly for analysis
3. Check serena MCP service status and retry (/mcp status)
Please choose handling method:"
User Choice Handling:
- Choice 1 → Route to zen-thinkdeep (alternative analysis)
- Choice 2 → Main Claude manual code reading
- Choice 3 → Wait for user to troubleshoot, then retry original request
Note: User-mentioned MCP tools are assumed available (optimistic),
but must provide clear error feedback if they fail at runtime.
Case 4: User Override
Scenario: User explicitly requests a different skill
User: "Don't use codex, use gemini to analyze"
Action:
Router Analysis:
- Original selection: codex-code-reviewer
- User override: Use gemini (deep-gemini)
→ Decision: Respect user choice
→ Route to: deep-gemini
→ Notification: "Switched to deep-gemini (as per your request)"
Notes
Core Principles
-
Active Task Monitoring (HIGHEST PRIORITY - Anti-Lazy Principle):
- Router MUST continuously monitor task lifecycle
- Proactively invoke skills at critical stages
- Mandatory skill usage rules (NEVER skip):
- plan.md → plan-down (MANDATORY)
- Code complete → codex-code-reviewer (MANDATORY)
- Test code → simple-gemini + codex validation (MANDATORY)
- Documentation → simple-gemini or deep-gemini (MANDATORY)
- Think at each stage: "Should I invoke a skill here?"
- Being lazy is FORBIDDEN - always use proper skills
-
Standards-First Approach: ALWAYS read CLAUDE.md before routing decisions
- Global CLAUDE.md:
/home/vc/.claude/CLAUDE.md
- Global CLAUDE.md:
/home/vc/.claude/CLAUDE.md
- Project CLAUDE.md:
./CLAUDE.md (if exists)
- Project CLAUDE.md:
./CLAUDE.md (if exists)
-
MCP-Aware Routing: Optimistic assumption with lazy verification
- zen-mcp assumed available by default - No pre-check required
- User-mentioned MCP tools assumed available - Honor user's explicit tool choice
- Route to skills immediately without MCP verification
- Verify MCP availability lazily (on actual tool invocation)
- Only communicate with user if MCP tools fail at runtime
- Optional: Discover serena/unifuncs MCPs on-demand for enhancements
- Provide fallback options when MCP tools actually fail
-
Proactive Usage: Main Router should be invoked for ALL task-related user requests
-
Standards Compliance: All routing decisions must align with documented rules
- Respect phase requirements (P1→P2→P3)
- Follow global rules (G1-G8)
- Apply project-specific overrides when applicable
Operation Modes
Best Practices
-
Transparency: Always inform user which skill/tool was selected and why
- Focus on intent match and standards alignment in routing notification
- Honor user's explicit MCP tool choice (e.g., "use serena") without pre-checking
- Only mention MCP status if there's a runtime failure
- Acknowledge when routing based on user's explicit MCP preference
-
Flexibility: Support user overrides and manual skill selection
- Allow user to choose alternative skills if zen-mcp fails at runtime
- Respect user's explicit skill preference
-
Efficiency: Prefer simpler skills when ambiguous
- simple-gemini over deep-gemini (unless "deep" mentioned)
- zen-chat over zen-thinkdeep (unless "investigate" or "bug" mentioned)
- Direct execution over complex skills when unclear
-
Context-Aware: Consider project state, recent activity, git status, and CLAUDE.md phase
- Leverage serena memory tools for project context (if discovered)
- Use git status to inform routing decisions
-
Multi-Skill Support: Handle sequential and parallel skill execution
- Route to multiple skills when user requests multi-task workflows
- Execute skills independently or sequentially as needed
-
Fallback Strategy: Graceful degradation on runtime failures
- zen-mcp fails → Notify user and suggest alternative skill or Main Claude
- Provide actionable troubleshooting steps (e.g., "/mcp status")
- Allow user to retry after troubleshooting
-
Continuous Improvement: Learn from user corrections and overrides
- Track skill selection patterns for future optimization
- Log runtime MCP failures for debugging
-
No Redundancy: Don't invoke router for meta-requests about the router itself
Router Self-Awareness
The router should NOT route these requests:
- "What skills are available?" → Direct answer
- "How does routing work?" → Direct answer
- "Explain the router" → Direct answer
- General questions about Claude Code or skills → Direct answer
The router SHOULD route these requests:
- General Q&A and explanations → zen-chat
- Deep problem investigation → zen-thinkdeep
- Any task-specific request (code review, docs, planning, analysis)
- Requests with explicit skill/tool names
- Requests with clear intent (review, generate, analyze, plan, explain, investigate)
