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

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

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

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

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

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

• Frontend Request Scoring: See Example 12 - Frontend Development Request for detailed demonstration of Tier 1-3 keyword detection and auto-routing (Score: 90 → gemini-frontend)
• Fullstack Project Handling: See Example 13 - Fullstack Project Detection for task decomposition strategy when both frontend and backend signals detected (Score: 45 with backend penalty → recommend split)

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):

1. Global CLAUDE.md (highest priority)
2. Project CLAUDE.md (overrides global)
3. PROJECTWIKI.md (lowest priority)

Phase 0.2: 动态 MCP 发现与智能适配（Dynamic MCP Discovery & Adaptation）

核心原则：不假设任何 MCP 工具"一定存在"，运行时动态检测并智能适配。

MCP 环境扫描策略

检测时机：

• 会话启动时：首次路由前执行快速扫描（可选，推荐）
• 运行时检测：技能调用 MCP 工具时懒加载检测（默认）
• 失败触发：MCP 调用失败时重新扫描并更新缓存

检测方法：

# 伪代码示例 - 动态 MCP 能力检测

mcp_capabilities = {}  # 会话级缓存

def detect_mcp_availability():
    """运行时检测 MCP 工具可用性"""

    # 1. 检测 zen-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}

    # 2. 检测 serena-mcp（代码智能）
    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}

    # 3. 检测 unifuncs-mcp（工具函数）
    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}

    # 4. 检测其他 MCP（用户自定义）
    # 可通过 ListMcpResourcesTool 发现额外 MCP 服务器

    return mcp_capabilities

技能 → MCP 依赖关系（动态映射）

技能与 MCP 工具的依赖分为三类：

1. 必需工具（Required）：技能核心功能依赖，缺失则无法工作
2. 增强工具（Enhancement）：提升技能能力，缺失可降级
3. 可选工具（Optional）：锦上添花，缺失无影响

动态依赖映射表：

G10 合规特殊要求：

• 使用 codex/gemini 模型时，必须先用 mcp__zen__clink 建立 CLI 会话
• plan-down 的四路径工作流：Phase 0 使用 chat 判断方法清晰度，Automatic + Unclear 路径需要 consensus

智能适配与降级策略

适配原则：

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

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

2. Router 自动选择技能时：

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

3. 降级决策树：

IF 技能必需工具全部可用:
    → 正常路由到该技能（最优方案）

ELSE IF 技能必需工具部分缺失:
    → 检查降级方案是否可行
    IF 降级方案可行:
        → 使用降级方案（通知用户，如果是显式请求）
    ELSE:
        → 通知用户工具缺失，请求确认或提供替代方案

ELSE IF 仅增强工具缺失:
    → 正常路由，静默降级（不通知用户）

降级方案示例：

运行时适配示例

示例 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:

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

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

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