# Main Router

> 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…

- **Type:** Skill
- **Install:** `agentstack add skill-vcnoc-claude-code-zen-mcp-skill-work-main-router`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [VCnoC](https://agentstack.voostack.com/s/vcnoc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [VCnoC](https://github.com/VCnoC)
- **Source:** https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work/tree/main/skills/main-router

## Install

```sh
agentstack add skill-vcnoc-claude-code-zen-mcp-skill-work-main-router
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 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

---

### 智能适配与降级策略

**适配原则：**

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

2. **Router 自动选择技能时**：
   - 根据 MCP 可用性调整技能推荐优先级
   - 必需工具不可用 → 降级到备用方案
   - 仅增强工具不可用 → 静默降级，不通知用户

3. **降级决策树**：

```
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" 强制重新扫描

**缓存数据结构：**

```python
# 示例缓存结构
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vcnoc-claude-code-zen-mcp-skill-work-main-router
- Seller: https://agentstack.voostack.com/s/vcnoc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.