docs: update Primary Agent and MCP API documentation

Update documentation for recently added features
README: Add Solution Architect and Technical Planner to Layer 2 Primary Agents (5 languages)
API docs: Document parse_mode response fields and new MCP tools
CHANGELOG: Add version 2.0.0 changes
Agents README: Add detailed documentation for Solution Architect and Technical Planner

no reference

Author: wishket-pjw

README.es.md

@@ -85,7 +85,7 @@ Añade a la configuración de Claude Desktop (`~/Library/Application Support/Cla
 Consulta el diagrama de arquitectura de arriba para una visión general del sistema de agentes de 3 capas:
 
 - **Layer 1 (Agentes de Modo)**: Ciclo de flujo de trabajo PLAN → ACT → EVAL
-- **Layer 2 (Agentes Principales)**: Frontend/Backend Developer, Code Reviewer, DevOps
+- **Layer 2 (Agentes Principales)**: Solution Architect, Technical Planner, Frontend/Backend Developer, Code Reviewer, DevOps
 - **Layer 3 (Especialistas)**: 9 expertos de dominio (Seguridad, Rendimiento, Accesibilidad, etc.)
 - **Habilidades**: Capacidades reutilizables (TDD, Depuración, Brainstorming, etc.)
 

README.ja.md

@@ -85,7 +85,7 @@ Claude Desktop設定に追加（`~/Library/Application Support/Claude/claude_des
 上記のアーキテクチャ図で3層エージェントシステムの全体像をご確認ください：
 
 - **Layer 1（モードエージェント）**：PLAN → ACT → EVAL ワークフローサイクル
-- **Layer 2（主要エージェント）**：Frontend/Backend Developer、Code Reviewer、DevOps
+- **Layer 2（主要エージェント）**：Solution Architect、Technical Planner、Frontend/Backend Developer、Code Reviewer、DevOps
 - **Layer 3（スペシャリスト）**：9名のドメイン専門家（セキュリティ、パフォーマンス、アクセシビリティなど）
 - **スキル**：再利用可能な機能（TDD、デバッグ、ブレインストーミングなど）
 

README.ko.md

@@ -85,7 +85,7 @@ Claude Desktop 설정 파일에 추가 (`~/Library/Application Support/Claude/cl
 위 아키텍처 다이어그램에서 3계층 에이전트 시스템의 전체 구조를 확인하세요:
 
 - **Layer 1 (모드 에이전트)**: PLAN → ACT → EVAL 워크플로우 사이클
-- **Layer 2 (주요 에이전트)**: Frontend/Backend Developer, Code Reviewer, DevOps
+- **Layer 2 (주요 에이전트)**: Solution Architect, Technical Planner, Frontend/Backend Developer, Code Reviewer, DevOps
 - **Layer 3 (전문가)**: 9명의 도메인 전문가 (보안, 성능, 접근성 등)
 - **스킬**: 재사용 가능한 기능 (TDD, 디버깅, 브레인스토밍 등)
 

README.md

@@ -85,7 +85,7 @@ Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_deskt
 See the architecture diagram above for a visual overview of the 3-layer agent system:
 
 - **Layer 1 (Mode Agents)**: PLAN → ACT → EVAL workflow cycle
-- **Layer 2 (Primary Agents)**: Frontend/Backend Developer, Code Reviewer, DevOps
+- **Layer 2 (Primary Agents)**: Solution Architect, Technical Planner, Frontend/Backend Developer, Code Reviewer, DevOps
 - **Layer 3 (Specialists)**: 9 domain experts (Security, Performance, Accessibility, etc.)
 - **Skills**: Reusable capabilities (TDD, Debugging, Brainstorming, etc.)
 

README.zh-CN.md

@@ -85,7 +85,7 @@ npx codingbuddy init
 请参阅上方架构图，了解三层代理系统的完整概览：
 
 - **Layer 1（模式代理）**：PLAN → ACT → EVAL 工作流程循环
-- **Layer 2（主要代理）**：Frontend/Backend Developer、Code Reviewer、DevOps
+- **Layer 2（主要代理）**：Solution Architect、Technical Planner、Frontend/Backend Developer、Code Reviewer、DevOps
 - **Layer 3（专家）**：9位领域专家（安全、性能、可访问性等）
 - **技能**：可复用功能（TDD、调试、头脑风暴等）
 

docs/api.md

@@ -130,9 +130,11 @@ Specialist agent definitions.
 
 | URI | Agent |
 |-----|-------|
-| `rules://agents/frontend-developer.json` | Frontend Developer |
-| `rules://agents/backend-developer.json` | Backend Developer |
-| `rules://agents/code-reviewer.json` | Code Reviewer |
+| `rules://agents/solution-architect.json` | Solution Architect (PLAN mode) |
+| `rules://agents/technical-planner.json` | Technical Planner (PLAN mode) |
+| `rules://agents/frontend-developer.json` | Frontend Developer (ACT mode) |
+| `rules://agents/backend-developer.json` | Backend Developer (ACT mode) |
+| `rules://agents/code-reviewer.json` | Code Reviewer (EVAL mode) |
 | `rules://agents/architecture-specialist.json` | Architecture Specialist |
 | `rules://agents/test-strategy-specialist.json` | Test Strategy Specialist |
 | `rules://agents/performance-specialist.json` | Performance Specialist |
@@ -309,12 +311,31 @@ Parse workflow mode keyword from prompt and return mode-specific rules with proj
   "content": [
     {
       "type": "text",
-      "text": "{\"mode\": \"PLAN\", \"prompt\": \"Design a user authentication feature\", \"instructions\": \"...\", \"rules\": \"...\", \"language\": \"ko\"}"
+      "text": "{\"mode\": \"PLAN\", \"originalPrompt\": \"Design a user authentication feature\", \"instructions\": \"...\", \"rules\": [...], \"agent\": \"plan-mode\", \"delegates_to\": \"technical-planner\", \"primary_agent_source\": \"intent\", \"delegate_agent_info\": {...}, \"parallelAgentsRecommendation\": {...}, \"languageInstruction\": \"Always respond in Korean.\", \"resolvedModel\": {\"model\": \"claude-sonnet-4-20250514\", \"source\": \"mode\"}}"
     }
   ]
 }
 ```
 
+**Response Fields**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mode` | string | Detected mode: `PLAN`, `ACT`, or `EVAL` |
+| `originalPrompt` | string | User prompt with keyword removed |
+| `instructions` | string | Mode-specific instructions |
+| `rules` | array | Applicable rule files with content |
+| `warnings` | array | Parsing warnings (optional) |
+| `agent` | string | Mode Agent name (e.g., `plan-mode`) |
+| `delegates_to` | string | Primary Agent name |
+| `primary_agent_source` | string | How Primary Agent was selected: `explicit`, `config`, `intent`, `context`, `default` |
+| `delegate_agent_info` | object | Primary Agent details (name, description, expertise) |
+| `parallelAgentsRecommendation` | object | Recommended specialist agents for parallel execution |
+| `recommended_act_agent` | object | Recommended ACT mode agent (for PLAN mode) |
+| `activation_message` | object | Agent activation transparency info |
+| `languageInstruction` | string | Dynamic language instruction based on config |
+| `resolvedModel` | object | Resolved AI model info (`model`, `source`) |
+
 **Mode Values**:
 
 | Mode | Trigger Keywords | Description |
@@ -508,6 +529,220 @@ recommend_skills({ prompt: "Build a dashboard component" })
 
 ---
 
+### list_skills
+
+List all available skills with optional priority filtering.
+
+**Input Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "minPriority": {
+      "type": "number",
+      "description": "Minimum priority threshold (inclusive)"
+    },
+    "maxPriority": {
+      "type": "number",
+      "description": "Maximum priority threshold (inclusive)"
+    }
+  },
+  "required": []
+}
+```
+
+**Request Example**:
+
+```json
+{
+  "name": "list_skills",
+  "arguments": {}
+}
+```
+
+**Response Example**:
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"skills\": [{\"name\": \"systematic-debugging\", \"priority\": 1, \"description\": \"Systematic approach to debugging\"}, {\"name\": \"test-driven-development\", \"priority\": 2, \"description\": \"TDD workflow\"}], \"total\": 10}"
+    }
+  ]
+}
+```
+
+**Response Fields**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `skills` | array | List of available skills |
+| `skills[].name` | string | Skill identifier |
+| `skills[].priority` | number | Skill priority (lower = higher priority) |
+| `skills[].description` | string | Brief description of the skill |
+| `total` | number | Total number of skills returned |
+
+**Filter Example**:
+
+```json
+{
+  "name": "list_skills",
+  "arguments": {
+    "minPriority": 1,
+    "maxPriority": 3
+  }
+}
+```
+
+---
+
+### get_agent_system_prompt
+
+Get complete system prompt for a specialist agent to be executed as a Claude Code subagent.
+
+**Input Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "agentName": {
+      "type": "string",
+      "description": "Name of the specialist agent (e.g., 'security-specialist', 'accessibility-specialist')"
+    },
+    "context": {
+      "type": "object",
+      "description": "Context for the agent",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["PLAN", "ACT", "EVAL"],
+          "description": "Current workflow mode"
+        },
+        "targetFiles": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Files to analyze or review"
+        },
+        "taskDescription": {
+          "type": "string",
+          "description": "Description of the task"
+        }
+      },
+      "required": ["mode"]
+    }
+  },
+  "required": ["agentName", "context"]
+}
+```
+
+**Request Example**:
+
+```json
+{
+  "name": "get_agent_system_prompt",
+  "arguments": {
+    "agentName": "security-specialist",
+    "context": {
+      "mode": "EVAL",
+      "targetFiles": ["src/auth/login.ts"],
+      "taskDescription": "Review authentication security"
+    }
+  }
+}
+```
+
+**Response Example**:
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"agentName\": \"security-specialist\", \"systemPrompt\": \"You are a Security Specialist agent...\", \"taskPrompt\": \"Analyze security of src/auth/login.ts...\"}"
+    }
+  ]
+}
+```
+
+---
+
+### prepare_parallel_agents
+
+Prepare multiple specialist agents for parallel execution via Claude Code Task tool.
+
+**Input Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["PLAN", "ACT", "EVAL"],
+      "description": "Current workflow mode"
+    },
+    "specialists": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of specialist agent names"
+    },
+    "targetFiles": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files to analyze or review"
+    },
+    "sharedContext": {
+      "type": "string",
+      "description": "Shared context or task description for all agents"
+    }
+  },
+  "required": ["mode", "specialists"]
+}
+```
+
+**Request Example**:
+
+```json
+{
+  "name": "prepare_parallel_agents",
+  "arguments": {
+    "mode": "EVAL",
+    "specialists": ["security-specialist", "accessibility-specialist", "performance-specialist"],
+    "targetFiles": ["src/components/UserForm.tsx"],
+    "sharedContext": "Review the user registration form"
+  }
+}
+```
+
+**Response Example**:
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"prepared\": [{\"agentName\": \"security-specialist\", \"systemPrompt\": \"...\", \"taskPrompt\": \"...\"}, ...], \"executionHint\": \"Use Task tool with subagent_type='general-purpose' and run_in_background=true\"}"
+    }
+  ]
+}
+```
+
+**Usage with Claude Code Task Tool**:
+
+```typescript
+// Launch multiple agents in parallel
+await Promise.all([
+  Task({ subagent_type: 'general-purpose', prompt: securityPrompt, run_in_background: true }),
+  Task({ subagent_type: 'general-purpose', prompt: accessibilityPrompt, run_in_background: true }),
+  Task({ subagent_type: 'general-purpose', prompt: performancePrompt, run_in_background: true })
+]);
+```
+
+---
+
 ## Prompts
 
 Prompts provide pre-defined message templates for common workflows.
@@ -584,7 +819,7 @@ Activate a specific specialist agent with project context.
 | `Invalid URI scheme` | URI doesn't start with `rules://` or `config://` | Use correct URI scheme |
 | `Resource not found: {uri}` | Requested rule file doesn't exist | Check file path in `packages/rules/.ai-rules/` |
 | `Agent '{name}' not found` | Invalid agent name | Use valid agent name from list |
-| `Tool not found: {name}` | Invalid tool name | Use one of: `search_rules`, `get_agent_details`, `parse_mode`, `get_project_config`, `suggest_config_updates`, `recommend_skills` |
+| `Tool not found: {name}` | Invalid tool name | Use one of: `search_rules`, `get_agent_details`, `parse_mode`, `get_project_config`, `suggest_config_updates`, `recommend_skills`, `list_skills`, `get_agent_system_prompt`, `prepare_parallel_agents` |
 | `Failed to load project configuration` | Missing or invalid `codingbuddy.config.js` | Run `npx codingbuddy init` |
 
 ---

packages/rules/.ai-rules/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to the Multi-AI Coding Assistant Common Rules System will be
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-01-06
+
+### Added
+
+- **PLAN Mode Primary Agents** with intent-based resolution
+  - `solution-architect.json`: High-level system design and architecture planning
+  - `technical-planner.json`: Low-level implementation planning with TDD and bite-sized tasks
+  - Intent-based automatic selection between architects based on prompt analysis
+  - Support for Korean and English intent patterns
+
+- **AI Model Selection and Resolution**
+  - CLI init prompt for model selection (Sonnet/Opus/Haiku)
+  - `ai.defaultModel` configuration field in `codingbuddy.config.js`
+  - Agent-level model preferences with priority resolution (agent > mode > system)
+  - `resolvedModel` field in MCP tool responses
+
+- **Parallel Agent Execution Support**
+  - `get_agent_system_prompt` MCP tool for generating subagent prompts
+  - `prepare_parallel_agents` MCP tool for batch agent preparation
+  - `parallelAgentsRecommendation` in `parse_mode` response
+  - Default specialist lists per mode (PLAN/ACT/EVAL)
+
+- **Dynamic Language Configuration**
+  - `LanguageService` supporting 10 languages (ko, en, ja, zh, es, de, fr, pt, ru, hi)
+  - `languageInstruction` field in `parse_mode` response
+  - Automatic language detection from project config
+
+- **Agent Activation Transparency**
+  - `ActivationMessageBuilder` for clear agent activation reporting
+  - `activation_message` field showing active agents with tiers
+
+### Changed
+
+- **Primary Agent Resolution**
+  - Extended `PrimaryAgentSource` type to include `intent`
+  - Priority order: explicit > config > intent > context > default
+  - Centralized Primary Agent constants with `_LIST` variants
+
+- **Token Usage Optimization**
+  - Mode-based `core.md` filtering to reduce token consumption
+  - Shared `ResponseUtils` for consolidated response generation
+
+### Fixed
+
+- Canary deployment timestamp mismatch bug
+- Type assertions replaced with proper typing in keyword service
+
+---
+
 ## [1.0.0] - 2025-11-20
 
 ### Added
@@ -48,18 +97,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added
-- **Clarification Phase** for PLAN mode (`rules/clarification-guide.md`)
-  - Optional phase triggered when AI detects ambiguous requirements
-  - Sequential Q&A with progress indicator (Question N/M format)
-  - Multiple-choice questions preferred for easy response
-  - Ambiguity assessment checklist (6 categories, triggers on 2+ unclear)
-  - Question count guidelines (2-7 questions based on complexity)
-  - Korean/English output format support
-  - Updated `rules/core.md` with Clarification Phase section
-
 ### Planned
-- Real-world usage testing across all 6 AI tools
+- Real-world usage testing across all 7 AI tools (including OpenCode)
 - Performance metrics collection
 - User feedback integration
 - Advanced examples and use cases