Main Router

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:

1. 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

1. 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)

1. 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

1. 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

1. 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:

1. Interactive Mode (Default):

• Router asks user for clarification when ambiguous
• User makes final decisions on skill selection
• Router provides recommendations with rationale

1. 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 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__readmemory (项目上下文)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

---

智能适配与降级策略

适配原则：

1. 用户显式指定 MCP 工具时：

• 优先尝试用户指定的工具
• 如果工具不可用，通知用户并提供替代方案
• 示例：用户说 "use serena to analyze code" → 检测 serena → 不可用则通知

1. Router 自动选择技能时：

• 根据 MCP 可用性调整技能推荐优先级
• 必需工具不可用 → 降级到备用方案
• 仅增强工具不可用 → 静默降级，不通知用户

1. 降级决策树：

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"
    }
}
`

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [VCnoC](https://github.com/VCnoC)
- **Source:** [VCnoC/Claude-Code-Zen-mcp-Skill-Work](https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.