codingbuddy-rules 1.2.0 → 1.3.0

package/.ai-rules/adapters/opencode-skills.md

@@ -0,0 +1,263 @@
+# OpenCode Skills Integration Guide
+
+This guide explains how to integrate `.ai-rules/skills/` with OpenCode/Crush's Agent Skills system.
+
+## Overview
+
+OpenCode/Crush supports Agent Skills standard for structured AI capabilities. This guide maps existing `.ai-rules/skills/` to OpenCode-compatible format and provides usage patterns.
+
+## Skills Mapping
+
+| .ai-rules Skill | OpenCode Usage | Agent Integration |
+|----------------|----------------|-------------------|
+| `brainstorming` | `/skill brainstorming` | plan agent |
+| `test-driven-development` | `/skill tdd` | build agent |
+| `systematic-debugging` | `/skill debug` | build agent |
+| `writing-plans` | `/skill planning` | plan agent |
+| `executing-plans` | `/skill execute` | build agent |
+| `frontend-design` | `/skill frontend` | build agent |
+| `dispatching-parallel-agents` | `/skill parallel` | plan agent |
+| `subagent-driven-development` | `/skill subagent` | plan agent |
+
+## Skills Configuration
+
+### For OpenCode (.opencode.json)
+```json
+{
+  "skills": {
+    "paths": [
+      "packages/rules/.ai-rules/skills"
+    ],
+    "auto_load": true
+  }
+}
+```
+
+### For Crush (crush.json)
+```json
+{
+  "options": {
+    "skills_paths": [
+      "packages/rules/.ai-rules/skills"
+    ],
+    "auto_suggest_skills": true
+  }
+}
+```
+
+## Usage Patterns
+
+### 1. Direct Skill Invocation
+```bash
+# In OpenCode CLI
+/skill brainstorming "새로운 기능 아이디어"
+/skill tdd "사용자 인증 구현"
+/skill debug "로그인 버그 해결"
+```
+
+### 2. Agent + Skill Combination
+```bash
+# Planning with brainstorming skill
+/agent plan
+/skill brainstorming "대시보드 UI 개선"
+
+# Implementation with TDD skill  
+/agent build
+/skill tdd "API 연동 구현"
+
+# Review with debugging skill
+/agent reviewer
+/skill debug "성능 이슈 분석"
+```
+
+### 3. Automatic Skill Recommendation
+
+OpenCode can automatically recommend skills based on prompts using the `recommend_skills` MCP tool:
+
+```typescript
+// Auto-triggered when user enters certain keywords
+"버그가 있어" → recommends: systematic-debugging
+"계획을 세워줘" → recommends: writing-plans  
+"UI를 만들어줘" → recommends: frontend-design
+```
+
+## Skill Conversion Process
+
+### 1. SKILL.md Format Compatibility
+
+Existing `.ai-rules/skills/*/SKILL.md` files are already compatible with Agent Skills standard:
+
+```markdown
+# Skill Name
+
+## Description
+Brief description of the skill's purpose
+
+## Usage
+When and how to use this skill
+
+## Steps
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Examples
+Example scenarios and outputs
+```
+
+### 2. No Conversion Required
+
+The existing skills can be used directly in OpenCode without modification:
+
+- **brainstorming/SKILL.md** ✅ Ready
+- **test-driven-development/SKILL.md** ✅ Ready
+- **systematic-debugging/SKILL.md** ✅ Ready
+- **writing-plans/SKILL.md** ✅ Ready
+- **executing-plans/SKILL.md** ✅ Ready
+- **frontend-design/SKILL.md** ✅ Ready
+- **dispatching-parallel-agents/SKILL.md** ✅ Ready
+- **subagent-driven-development/SKILL.md** ✅ Ready
+
+## Integration with MCP
+
+### Codingbuddy MCP Skills
+
+The `codingbuddy` MCP server provides skill recommendation:
+
+```json
+{
+  "mcp": {
+    "codingbuddy": {
+      "type": "stdio",
+      "command": ["npx", "codingbuddy@latest", "mcp"]
+    }
+  }
+}
+```
+
+**Available MCP tools:**
+- `recommend_skills`: Get skill recommendations based on user prompt
+- `get_skill`: Load specific skill content
+- `list_skills`: List all available skills
+
+### Automatic Skill Loading
+
+OpenCode agents can automatically load relevant skills:
+
+```json
+{
+  "agent": {
+    "plan": {
+      "auto_skills": ["brainstorming", "writing-plans"],
+      "systemPrompt": "You have access to brainstorming and planning skills..."
+    },
+    "build": {
+      "auto_skills": ["test-driven-development", "executing-plans", "frontend-design"],
+      "systemPrompt": "You have access to TDD, execution, and frontend skills..."
+    }
+  }
+}
+```
+
+## Workflow Integration
+
+### PLAN Mode Skills
+When using `plan` agent, automatically suggest:
+- **brainstorming**: For ideation and requirements exploration
+- **writing-plans**: For structured implementation planning
+- **dispatching-parallel-agents**: For complex multi-component features
+
+### ACT Mode Skills  
+When using `build` agent, automatically suggest:
+- **test-driven-development**: For core logic implementation
+- **executing-plans**: For systematic plan execution
+- **frontend-design**: For UI component development
+- **systematic-debugging**: When encountering issues
+
+### EVAL Mode Skills
+When using `reviewer` agent, automatically suggest:
+- **systematic-debugging**: For error analysis
+- **subagent-driven-development**: For improvement strategies
+
+## Korean Language Support
+
+All skills support Korean language through MCP integration:
+
+```bash
+# Korean skill invocation
+/skill 브레인스토밍 "새로운 기능"
+/skill TDD개발 "사용자 관리"
+/skill 디버깅 "성능 문제"
+```
+
+The MCP server handles Korean→English skill name mapping automatically.
+
+## Examples
+
+### Planning a New Feature
+
+```bash
+# Start planning session
+/agent plan
+
+# Use brainstorming skill
+/skill brainstorming "사용자 대시보드 개선"
+
+# Generate implementation plan
+계획을 세워줘
+```
+
+### Implementing with TDD
+
+```bash  
+# Switch to build agent
+/agent build
+
+# Load TDD skill
+/skill test-driven-development "로그인 API 구현"
+
+# Start TDD cycle
+ACT
+```
+
+### Debugging Issues
+
+```bash
+# Use systematic debugging
+/skill systematic-debugging "로그인 후 화면이 안 나와"
+
+# Apply debugging methodology
+디버깅해줘
+```
+
+## Benefits
+
+### ✅ Advantages
+- **No Migration Required**: Existing skills work as-is
+- **Automatic Recommendations**: MCP-powered skill suggestions
+- **Korean Support**: Full Korean language integration
+- **Agent Integration**: Skills work seamlessly with agent modes
+- **Workflow Enhancement**: Skills enhance PLAN/ACT/EVAL workflow
+
+### ✅ Enhanced Capabilities
+- **Context-Aware**: Skills adapt to current agent mode
+- **Progressive Enhancement**: Skills complement agent capabilities
+- **Structured Approach**: Consistent methodology across skills
+- **Quality Focus**: Skills reinforce .ai-rules standards
+
+## Maintenance
+
+### Adding New Skills
+
+1. Create new skill directory: `packages/rules/.ai-rules/skills/new-skill/`
+2. Add `SKILL.md` file following Agent Skills format
+3. Skills automatically available in OpenCode
+4. Update skill mappings in this guide
+
+### Updating Existing Skills
+
+1. Modify skill content in `packages/rules/.ai-rules/skills/*/SKILL.md`
+2. Changes automatically reflected in OpenCode
+3. No configuration updates required
+
+This integration provides seamless skills access within OpenCode while maintaining consistency with the broader `.ai-rules` ecosystem.

package/.ai-rules/adapters/opencode.md

@@ -0,0 +1,457 @@
+# OpenCode Integration Guide
+
+This guide explains how to use the common AI rules (`.ai-rules/`) in OpenCode and its successor Crush.
+
+## Overview
+
+OpenCode (now evolved as "Crush" by Charm Bracelet) uses JSON configuration files to define agents, context paths, and tool permissions. This guide helps integrate the `.ai-rules/` system with OpenCode's agent-based workflow.
+
+## Project Status
+
+⚠️ **Important**: The original OpenCode project has been archived (September 2025) and continued as **"Crush"** by Charm Bracelet with 16.7k+ stars. This guide supports both versions.
+
+- **OpenCode**: Uses `.opencode.json` configuration
+- **Crush**: Uses `crush.json` or `~/.config/crush/crush.json` configuration
+
+## Integration Method
+
+### 1. Configure OpenCode/Crush Settings
+
+Update your configuration file (`.opencode.json` or `crush.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-20250514",
+  "default_agent": "plan-mode",
+
+  "instructions": [
+    "packages/rules/.ai-rules/rules/core.md",
+    "packages/rules/.ai-rules/rules/augmented-coding.md", 
+    "packages/rules/.ai-rules/rules/project.md",
+    "packages/rules/.ai-rules/adapters/opencode.md",
+    "CLAUDE.md"
+  ],
+
+  "agent": {
+    "plan-mode": {
+      "description": "PLAN mode - Analysis and planning without changes",
+      "mode": "primary",
+      "prompt": "{file:packages/rules/.ai-rules/agents/plan-mode.json}\n\n[OpenCode Override]\nMode: PLAN only. Always respond in Korean. Do NOT make any file changes. Focus on analysis and planning.",
+      "permission": {
+        "edit": "deny",
+        "bash": {
+          "git status": "allow",
+          "git diff*": "allow", 
+          "git log*": "allow",
+          "*": "ask"
+        }
+      }
+    },
+    "act-mode": {
+      "description": "ACT mode - Full development with all tools",
+      "mode": "primary",
+      "prompt": "{file:packages/rules/.ai-rules/agents/act-mode.json}\n\n[OpenCode Override]\nMode: ACT. Always respond in Korean. Follow TDD workflow and code quality standards.",
+      "permission": {
+        "edit": "allow",
+        "bash": "allow"
+      }
+    },
+    "eval-mode": {
+      "description": "EVAL mode - Code quality evaluation", 
+      "mode": "subagent",
+      "prompt": "{file:packages/rules/.ai-rules/agents/eval-mode.json}\n\n[OpenCode Override]\nMode: EVAL. Always respond in Korean. Provide evidence-based evaluation.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    }
+  },
+
+  "mcp": {
+    "codingbuddy": {
+      "type": "local",
+      "command": ["npx", "codingbuddy@latest", "mcp"]
+    }
+  }
+}
+```
+
+### 2. Agent System Mapping
+
+| Codingbuddy Agent | OpenCode Agent | Purpose |
+|------------------|----------------|---------|
+| **plan-mode.json** | `plan-mode` | PLAN mode workflow (delegates to frontend-developer) |
+| **act-mode.json** | `act-mode` | ACT mode workflow (delegates to frontend-developer) |
+| **eval-mode.json** | `eval-mode` | EVAL mode workflow (delegates to code-reviewer) |
+| **frontend-developer.json** | N/A (delegate) | Primary development implementation |
+| **code-reviewer.json** | N/A (delegate) | Code quality evaluation implementation |
+| **architecture-specialist.json** | `architect` | Architecture and design patterns |
+| **test-strategy-specialist.json** | `tester` | Test strategy and TDD |
+| **security-specialist.json** | `security` | Security audit |
+| **accessibility-specialist.json** | `a11y` | WCAG compliance |
+| **performance-specialist.json** | `performance` | Performance optimization |
+
+#### Mode Agent vs Specialist Agent
+
+- **Mode Agents** (`plan-mode`, `act-mode`, `eval-mode`): Workflow orchestrators that delegate to appropriate implementation agents
+- **Specialist Agents** (`architect`, `security`, etc.): Domain-specific expertise for specialized tasks
+- **Delegate Agents** (`frontend-developer`, `code-reviewer`): Implementation agents that Mode Agents delegate to
+
+### 3. MCP Server Integration
+
+#### Codingbuddy MCP Server
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcp": {
+    "codingbuddy": {
+      "type": "local",
+      "command": ["npx", "codingbuddy@latest", "mcp"],
+      "env": ["NODE_ENV=production"]
+    }
+  }
+}
+```
+
+#### Available MCP Tools
+
+Once connected, you can use:
+- `search_rules`: Query AI rules and guidelines
+- `get_agent_details`: Get specialist agent information
+- `recommend_skills`: Get skill recommendations based on prompt
+- `parse_mode`: Parse PLAN/ACT/EVAL workflow mode (now returns Mode Agent information)
+
+#### Enhanced parse_mode Response
+
+The `parse_mode` tool now returns additional Mode Agent information:
+
+```json
+{
+  "mode": "PLAN",
+  "originalPrompt": "새로운 사용자 등록 기능을 만들어줘",
+  "instructions": "설계 우선 접근. TDD 관점에서...",
+  "rules": [...],
+  "agent": "plan-mode",
+  "delegates_to": "frontend-developer", 
+  "delegate_agent_info": {
+    "name": "Frontend Developer",
+    "description": "React/Next.js 전문가, TDD 및 디자인 시스템 경험",
+    "expertise": ["React", "Next.js", "TDD", "TypeScript"]
+  }
+}
+```
+
+**New Fields:**
+- `agent`: Mode Agent name (plan-mode, act-mode, eval-mode)
+- `delegates_to`: Which specialist agent the Mode Agent delegates to
+- `delegate_agent_info`: Detailed information about the delegate agent (optional)
+
+**Backward Compatibility:** All new fields are optional. Existing clients continue to work unchanged.
+
+## Usage Workflows
+
+### PLAN → ACT → EVAL Workflow
+
+#### 1. Start with PLAN Mode
+
+```bash
+# In OpenCode CLI
+/agent plan-mode
+
+# Then in chat
+새로운 사용자 등록 기능을 만들어줘
+```
+
+**Plan-mode agent will:**
+- Analyze requirements (Korean response)
+- Create structured implementation plan
+- Generate todo list using todo_write tool
+- Reference .ai-rules for consistent standards
+
+#### 2. Execute with ACT Mode
+
+```bash
+# Switch to act agent
+/agent act-mode
+
+# Continue implementation
+ACT
+```
+
+**Act-mode agent will:**
+- Execute TDD workflow (Red → Green → Refactor)
+- Implement code following .ai-rules standards
+- Maintain 90%+ test coverage
+- Use TypeScript strict mode (no `any`)
+
+#### 3. Evaluate with EVAL Mode
+
+```bash
+# Switch to eval agent
+/agent eval-mode
+
+# Request evaluation
+EVAL
+```
+
+**Eval-mode agent will:**
+- Provide evidence-based code review
+- Check SOLID principles compliance
+- Verify security and accessibility standards
+- Reference specialist frameworks
+
+### Direct Agent Usage
+
+```bash
+# Use specific specialist agents
+/agent architect    # Architecture review
+/agent security    # Security audit  
+/agent a11y        # Accessibility check
+/agent performance # Performance optimization
+```
+
+## Custom Commands
+
+Create workflow commands in `~/.config/opencode/commands/` or `~/.config/crush/commands/`:
+
+### PLAN Command (`plan-feature.md`)
+```markdown
+READ {file:packages/rules/.ai-rules/rules/core.md}
+READ {file:packages/rules/.ai-rules/rules/project.md}
+ANALYZE $FEATURE_REQUIREMENTS
+CREATE implementation plan following TDD principles
+GENERATE todo list with priorities
+```
+
+### ACT Command (`implement-tdd.md`)
+```markdown
+READ {file:packages/rules/.ai-rules/rules/augmented-coding.md}
+FOLLOW Red → Green → Refactor cycle
+MAINTAIN 90%+ test coverage
+USE TypeScript strict mode
+COMMIT after each green phase
+```
+
+### EVAL Command (`code-review.md`)
+```markdown
+READ {file:packages/rules/.ai-rules/agents/code-reviewer.json}
+ANALYZE code quality with evidence
+CHECK SOLID principles
+VERIFY security and accessibility
+PROVIDE improvement recommendations
+```
+
+## Directory Structure
+
+```
+project/
+├── .opencode.json           # OpenCode configuration
+├── crush.json               # Crush configuration (alternative)
+├── packages/rules/.ai-rules/
+│   ├── adapters/
+│   │   └── opencode.md      # This guide
+│   ├── agents/
+│   │   ├── frontend-developer.json
+│   │   ├── code-reviewer.json
+│   │   └── *.json
+│   ├── rules/
+│   │   ├── core.md
+│   │   ├── project.md
+│   │   └── augmented-coding.md
+│   └── skills/
+│       └── */SKILL.md
+└── ~/.config/opencode/      # User-specific settings
+    └── commands/            # Custom workflow commands
+```
+
+## Crush-Specific Features
+
+For Crush users, additional features available:
+
+### Multi-Model Support
+```json
+{
+  "agents": {
+    "coder": { "model": "claude-3.7-sonnet", "maxTokens": 5000 },
+    "task": { "model": "gpt-4o", "maxTokens": 3000 },
+    "title": { "model": "claude-3.7-sonnet", "maxTokens": 80 }
+  }
+}
+```
+
+### LSP Integration
+```json
+{
+  "lsp": {
+    "typescript": { 
+      "command": "typescript-language-server",
+      "args": ["--stdio"] 
+    },
+    "go": { "command": "gopls" }
+  }
+}
+```
+
+### Skills System
+```json
+{
+  "options": {
+    "skills_paths": [
+      "packages/rules/.ai-rules/skills",
+      "~/.config/crush/skills"
+    ]
+  }
+}
+```
+
+## Benefits
+
+### ✅ Advantages
+
+- **Terminal-native**: Developer-friendly TUI interface
+- **Multi-session Management**: Project-specific context isolation
+- **Agent-based Workflow**: Clear separation of concerns
+- **Consistent Standards**: Same rules across all AI tools
+- **MCP Integration**: Access to specialized tools and knowledge
+- **Korean Language Support**: Full Korean responses configured
+
+### ✅ Key Features
+
+- **Dynamic Model Switching**: Change AI models during session
+- **Advanced Permissions**: Fine-grained tool access control
+- **Auto-initialization**: Project-specific context loading
+- **File Reference System**: `{file:path}` syntax for instructions
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Permission Denied**
+```bash
+# Check current agent permissions
+/agent info
+
+# Switch to appropriate agent
+/agent act-mode  # For file editing
+/agent plan-mode # For read-only analysis
+```
+
+**2. MCP Connection Failed**
+```bash
+# Verify codingbuddy installation
+npx codingbuddy@latest --version
+
+# Test MCP connection
+npx codingbuddy@latest mcp
+```
+
+**3. Agent Not Responding in Korean**
+- Verify `[OpenCode Override]` includes Korean language setting
+- Check agent prompt includes language instruction
+
+### Migration from OpenCode to Crush
+
+1. **Rename configuration file**: `.opencode.json` → `crush.json`
+2. **Update schema reference**: Use Crush schema URL
+3. **Install Crush**: `brew install charmbracelet/tap/crush`
+4. **Migrate sessions**: Export/import session data
+
+## Maintenance
+
+### Updating Rules
+
+**For universal changes:**
+1. Edit files in `packages/rules/.ai-rules/`
+2. Changes automatically apply to all agents
+
+**For OpenCode-specific changes:**
+1. Update agent prompts in configuration file
+2. Modify custom commands in commands directory
+
+### Version Compatibility
+
+- **OpenCode 0.x**: Use `.opencode.json`
+- **Crush 1.x+**: Use `crush.json` or global config
+- **Both**: Maintain separate config files
+
+## Advanced Usage
+
+### Parallel Agent Workflows
+
+```bash
+# Terminal 1: Planning
+opencode --agent plan
+계획을 세워줘
+
+# Terminal 2: Implementation  
+opencode --agent build
+ACT
+
+# Terminal 3: Review
+opencode --agent reviewer
+EVAL
+```
+
+### Custom Agent Creation
+
+```json
+{
+  "agent": {
+    "custom": {
+      "description": "Custom specialist agent",
+      "mode": "subagent", 
+      "prompt": "{file:packages/rules/.ai-rules/agents/custom-specialist.json}",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": false
+      }
+    }
+  }
+}
+```
+
+## Examples
+
+### Frontend Development Session
+
+```bash
+# 1. Start planning
+/agent plan-mode
+React 컴포넌트 라이브러리를 만들어줘
+
+# 2. Implement
+/agent act-mode  
+ACT
+
+# 3. Review
+/agent eval-mode
+EVAL
+
+# 4. Optimize
+/agent performance
+성능 최적화 제안해줘
+```
+
+### Full-Stack Development
+
+```bash
+# Frontend work
+/agent plan-mode
+사용자 대시보드 UI 계획
+
+# Backend work  
+/agent backend
+API 엔드포인트 구현
+
+# Security review
+/agent security
+보안 취약점 검사
+```
+
+---
+
+This guide ensures consistent, high-quality AI-assisted development using OpenCode/Crush with the `.ai-rules` system. All agents follow the same standards while leveraging OpenCode's powerful terminal-based interface.

package/.ai-rules/agents/README.md

@@ -8,7 +8,7 @@ AI Agent definitions for specialized development roles.
 
 - [Quick Reference: Which Agent?](#quick-reference-which-agent)
 - [Available Agents](#available-agents)
-  - [Core Agents](#core-agents-auto-activated)
+  - [Core Agents](#core-agents-auto-activated-via-delegation)
   - [Domain Specialists](#domain-specialists)
   - [Utility Agents](#utility-agents)
 - [Agent Details](#agent-details)
@@ -58,16 +58,125 @@ AI Agent definitions for specialized development roles.
 
 ---
 
+## Mode Agents
+
+**New Agent Hierarchy**: Mode Agents → Delegate Agents → Specialist Agents
+
+Mode Agents are workflow orchestrators that provide seamless integration with OpenCode and other agent-based AI tools. They automatically delegate to appropriate specialist agents based on the workflow mode.
+
+### Mode Agent Hierarchy
+
+```
+Mode Agents (Workflow Orchestrators)
+├── plan-mode      → delegates to → frontend-developer (or project-specific)
+├── act-mode       → delegates to → frontend-developer (or project-specific)
+└── eval-mode      → delegates to → code-reviewer
+
+Delegate Agents (Implementation Experts)
+├── frontend-developer     # React/Next.js expertise
+├── backend-developer      # Multi-language backend expertise
+└── code-reviewer         # Quality evaluation expertise
+
+Specialist Agents (Domain Experts)
+├── architecture-specialist
+├── security-specialist
+├── accessibility-specialist
+└── ... (other specialists)
+```
+
+### Mode Agent Details
+
+| Mode Agent | Workflow | Delegates To | Purpose |
+|------------|----------|--------------|---------|
+| **plan-mode** | PLAN | frontend-developer (configurable) | Analysis and planning without changes |
+| **act-mode** | ACT | frontend-developer (configurable) | Full development with all tools |
+| **eval-mode** | EVAL | code-reviewer | Code quality evaluation |
+
+**Key Features:**
+- **Seamless Integration**: Works with OpenCode agent system
+- **Automatic Delegation**: Mode Agents handle workflow, Delegates handle implementation
+- **Flexible Configuration**: Delegate target configurable per project
+- **Backward Compatible**: Existing usage patterns continue to work
+
+### Usage with Mode Agents
+
+#### OpenCode/Agent-Based Tools
+
+```bash
+# OpenCode CLI example
+/agent plan-mode
+새로운 기능을 만들어줘
+
+/agent act-mode  
+ACT
+
+/agent eval-mode
+EVAL
+```
+
+#### MCP Integration
+
+When using the `parse_mode` MCP tool, you receive enhanced response with Mode Agent information:
+
+```json
+{
+  "mode": "PLAN",
+  "originalPrompt": "새로운 기능을 만들어줘",
+  "instructions": "설계 우선 접근...",
+  "rules": [{"name": "rules/core.md", "content": "..."}],
+  "warnings": ["No keyword found, defaulting to PLAN"],
+  "agent": "plan-mode",
+  "delegates_to": "frontend-developer",
+  "delegate_agent_info": {
+    "name": "Frontend Developer",
+    "description": "React/Next.js 전문가, TDD 및 디자인 시스템 경험",
+    "expertise": ["React", "Next.js", "TDD", "TypeScript"]
+  }
+}
+```
+
+**Response Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `mode` | string | Yes | Detected mode: "PLAN", "ACT", or "EVAL" |
+| `originalPrompt` | string | Yes | User prompt with keyword removed |
+| `instructions` | string | Yes | Mode-specific instructions |
+| `rules` | array | Yes | Applicable rule files with content |
+| `warnings` | array | No | Parsing warnings (e.g., missing keyword) |
+| `agent` | string | No | Mode Agent name (e.g., "plan-mode") |
+| `delegates_to` | string | No | Delegate agent name (e.g., "frontend-developer") |
+| `delegate_agent_info` | object | No | Delegate agent details (name, description, expertise) |
+
+### Agent Priority System
+
+Agents are listed in priority order:
+1. **Mode Agents** (plan-mode, act-mode, eval-mode)
+2. **Delegate Agents** (alphabetical)
+3. **Specialist Agents** (alphabetical)
+
+This ensures Mode Agents appear first in agent selection interfaces.
+
+---
+
 ## Available Agents
 
-### Core Agents (Auto-activated)
+### Mode Agents (Workflow Orchestrators)
+
+Mode Agents handle workflow orchestration and delegate to implementation experts:
+
+- **Plan Mode** (`plan-mode.json`): Analysis and planning (delegates to primary developer)
+- **Act Mode** (`act-mode.json`): Implementation execution (delegates to primary developer)  
+- **Eval Mode** (`eval-mode.json`): Quality evaluation (delegates to code reviewer)
+
+### Core Agents (Auto-activated via delegation)
 
-These agents are automatically activated based on workflow mode:
+These agents are automatically activated via Mode Agent delegation:
 
-- **Primary Developer Agent**: Auto-activated in PLAN/ACT mode
+- **Primary Developer Agent**: Activated by plan-mode/act-mode
   - Example: `frontend-developer.json` (React/Next.js projects)
   - Customize per project: `backend-developer.json`, `mobile-developer.json`, etc.
-- **Code Reviewer** (`code-reviewer.json`): Auto-activated in EVAL mode
+- **Code Reviewer** (`code-reviewer.json`): Activated by eval-mode
 
 ### Domain Specialists
 

package/.ai-rules/agents/act-mode.json

@@ -0,0 +1,158 @@
+{
+  "name": "Act Mode Agent",
+  "description": "ACT 모드 전용 에이전트 - 실제 구현 실행에 특화",
+
+  "role": {
+    "title": "Act Mode Agent",
+    "mode": "ACT",
+    "purpose": "Mode Agent - delegates to Primary Developer Agent",
+    "expertise": [
+      "TDD 사이클 실행 (Red → Green → Refactor)",
+      "코드 품질 기준 준수",
+      "타입 안전성 보장",
+      "테스트 커버리지 90%+ 달성",
+      "실시간 품질 검증"
+    ],
+    "delegates_to": "frontend-developer",
+    "responsibilities": [
+      "PLAN 모드에서 정의된 계획 실행",
+      "TDD 사이클 엄격히 준수 (Red → Green → Refactor)",
+      "코어 로직: Test-First, UI 컴포넌트: Test-After 접근",
+      "타입 안전성 유지 (TypeScript strict mode, no any)",
+      "테스트 커버리지 90%+ 목표 달성",
+      "SOLID 원칙 및 코드 품질 기준 유지",
+      "프레임워크별 컴포넌트 패턴 준수",
+      "디자인 시스템 우선 사용",
+      "접근성 및 성능 최적화 적용"
+    ]
+  },
+
+  "context_files": [
+    ".ai-rules/rules/core.md",
+    ".ai-rules/rules/project.md",
+    ".ai-rules/rules/augmented-coding.md"
+  ],
+
+  "activation": {
+    "trigger": "🔴 **STRICT**: When user types 'ACT' or equivalent (Korean: 실행, Japanese: 実行, Chinese: 执行, Spanish: ACTUAR)",
+    "rule": "🔴 **STRICT**: ACT MODE request must activate this Agent automatically",
+    "mandatory_checklist": {
+      "🔴 language": {
+        "rule": "MUST respond in Korean as specified in communication.language",
+        "verification_key": "language"
+      },
+      "🔴 tdd_cycle": {
+        "rule": "MUST follow TDD cycle for core logic (Red → Green → Refactor)",
+        "verification_key": "tdd_cycle"
+      },
+      "🔴 mode_indicator": {
+        "rule": "MUST print '# Mode: ACT' as first line of response",
+        "verification_key": "mode_indicator"
+      },
+      "🔴 agent_indicator": {
+        "rule": "MUST print '## Agent : Frontend Developer' (or appropriate delegate agent)",
+        "verification_key": "agent_indicator"
+      },
+      "🔴 delegate_activation": {
+        "rule": "MUST activate delegate agent (frontend-developer) framework for implementation execution",
+        "verification_key": "delegate_activation"
+      },
+      "🔴 auto_return_to_plan": {
+        "rule": "MUST automatically return to PLAN mode after ACT completes (default behavior)",
+        "verification_key": "auto_return_to_plan"
+      }
+    }
+  },
+
+  "workflow": {
+    "tdd_execution": {
+      "core_logic": "Red (failing test) → Green (minimal code) → Refactor (only after tests pass)",
+      "ui_components": "Implement → Test → Refactor",
+      "verification": "Run tests after each step, ensure 90%+ coverage"
+    },
+    "implementation_approach": {
+      "type_safety": "TypeScript strict mode, explicit types, no any usage",
+      "component_strategy": "Follow framework-specific patterns, prioritize design system components",
+      "quality_standards": "SOLID principles, DRY, pure/impure function separation",
+      "specialist_verification": "Reference Implementation Specialist Agents when needed (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)"
+    }
+  },
+
+  "mode_specific": {
+    "implementation_output": {
+      "step_by_step": "Show implementation progress with specific files created/modified",
+      "quality_verification": "Verify type safety, tests, linting, design system usage",
+      "todo_updates": "Mark todo items as completed after each successful implementation",
+      "auto_return": "Automatically return to PLAN mode after implementation completes"
+    }
+  },
+
+  "delegate_agent": {
+    "primary": "frontend-developer",
+    "description": "이 Mode Agent는 Frontend Developer Agent의 implementation 워크플로우를 활용합니다",
+    "integration": "Frontend Developer Agent의 TDD cycle과 code quality checklist를 적용"
+  },
+
+  "tdd_cycle": {
+    "red_phase": {
+      "purpose": "Write failing test that defines expected behavior",
+      "rules": [
+        "Write one test at a time",
+        "Test should fail for the right reason",
+        "Cover edge cases and error scenarios"
+      ]
+    },
+    "green_phase": {
+      "purpose": "Implement minimum code to make test pass",
+      "rules": [
+        "Simplest implementation possible",
+        "Focus only on making current test pass",
+        "No premature optimization"
+      ]
+    },
+    "refactor_phase": {
+      "purpose": "Improve code structure without changing behavior",
+      "rules": [
+        "Only refactor when all tests are green",
+        "Extract methods, improve names, remove duplication",
+        "Run tests after each refactor step"
+      ]
+    }
+  },
+
+  "quality_standards": {
+    "type_safety": "No any, unknown, or unsafe type bypasses",
+    "test_coverage": "90%+ for core logic, comprehensive for UI components",
+    "code_quality": "SOLID principles, DRY, complexity management",
+    "framework_compliance": "Follow project-specific component patterns",
+    "accessibility": "WCAG 2.1 AA compliance",
+    "performance": "Core Web Vitals optimization"
+  },
+
+  "communication": {
+    "language": "ko",
+    "style": "실행 중심의 단계별 진행 보고",
+    "format": "구현 진행상황과 품질 검증 결과를 명확히 표시"
+  },
+
+  "verification_guide": {
+    "mode_compliance": [
+      "✅ '# Mode: ACT' 표시 확인",
+      "✅ '## Agent : Frontend Developer' (또는 적절한 delegate) 표시 확인",
+      "✅ Korean 응답 확인",
+      "✅ TDD 사이클 준수 (Red → Green → Refactor) 확인",
+      "✅ 타입 안전성 (no any) 확인",
+      "✅ 테스트 커버리지 90%+ 확인",
+      "✅ Todo 항목 completed로 업데이트 확인",
+      "✅ ACT 완료 후 PLAN 모드로 자동 복귀 확인",
+      "✅ Delegate Agent의 implementation 워크플로우 적용 확인"
+    ],
+    "implementation_verification": [
+      "✅ 실제 구현 완료 (파일 생성/수정)",
+      "✅ 테스트 작성 및 통과",
+      "✅ 타입 정의 완료",
+      "✅ 린팅 에러 해결",
+      "✅ 디자인 시스템 컴포넌트 활용"
+    ]
+  }
+}

package/.ai-rules/agents/eval-mode.json

@@ -0,0 +1,175 @@
+{
+  "name": "Eval Mode Agent",
+  "description": "EVAL 모드 전용 에이전트 - 코드 품질 평가 및 개선안 제시에 특화",
+
+  "role": {
+    "title": "Eval Mode Agent",
+    "mode": "EVAL",
+    "purpose": "Mode Agent - delegates to Code Reviewer Agent",
+    "expertise": [
+      "다차원 코드 품질 평가",
+      "증거 기반 분석 (웹 검색 검증)",
+      "리스크 평가 및 우선순위 설정",
+      "개선안 제시",
+      "프로덕션 준비도 검토"
+    ],
+    "delegates_to": "code-reviewer",
+    "responsibilities": [
+      "ACT 모드에서 구현된 코드의 종합적 품질 평가",
+      "코드 품질, 아키텍처, 성능, 보안, 접근성 등 다차원 분석",
+      "웹 검색을 통한 증거 기반 권장사항 제시",
+      "Critical/High/Medium/Low 우선순위로 리스크 분류",
+      "구체적이고 실행 가능한 개선 계획 제시",
+      "Todo 리스트 생성 (todo_write 도구 활용)",
+      "프로덕션 배포 차단 요소 식별",
+      "Anti-Sycophancy 원칙 적용 (객관적 평가, 문제점 우선 식별)"
+    ]
+  },
+
+  "context_files": [
+    ".ai-rules/rules/core.md",
+    ".ai-rules/rules/augmented-coding.md"
+  ],
+
+  "activation": {
+    "trigger": "🔴 **STRICT**: When user types 'EVAL', 'EVALUATE' or equivalent (Korean: 평가해/개선안 제시해, Japanese: 評価, Chinese: 评估, Spanish: EVALUAR)",
+    "rule": "🔴 **STRICT**: EVAL MODE request must activate this Agent automatically",
+    "mandatory_checklist": {
+      "🔴 language": {
+        "rule": "MUST respond in Korean as specified in communication.language",
+        "verification_key": "language"
+      },
+      "🔴 mode_indicator": {
+        "rule": "MUST print '# Mode: EVAL' as first line of response",
+        "verification_key": "mode_indicator"
+      },
+      "🔴 agent_indicator": {
+        "rule": "MUST print '## Agent : Code Reviewer' (delegate agent)",
+        "verification_key": "agent_indicator"
+      },
+      "🔴 delegate_activation": {
+        "rule": "MUST activate delegate agent (code-reviewer) evaluation framework",
+        "verification_key": "delegate_activation"
+      },
+      "🔴 anti_sycophancy": {
+        "rule": "MUST apply Anti-Sycophancy rules (evaluate OUTPUT only, not INTENT, identify at least 3 improvement areas)",
+        "verification_key": "anti_sycophancy"
+      },
+      "🔴 evidence_based": {
+        "rule": "MUST validate recommendations through web search for evidence",
+        "verification_key": "evidence_based"
+      },
+      "🔴 todo_creation": {
+        "rule": "MUST create improvement todo list using todo_write tool",
+        "verification_key": "todo_creation"
+      }
+    }
+  },
+
+  "workflow": {
+    "evaluation_approach": {
+      "multi_dimensional": "Evaluate from code quality, architecture, performance, security, accessibility perspectives",
+      "evidence_based": "Validate all recommendations through web search with references",
+      "objective_metrics": "Use measurable criteria (coverage %, complexity scores, performance metrics)",
+      "risk_prioritization": "Classify issues as Critical/High/Medium/Low with clear impact assessment"
+    }
+  },
+
+  "mode_specific": {
+    "evaluation_framework": {
+      "mandatory_perspectives": [
+        "Code Quality: SOLID principles, DRY, complexity analysis",
+        "Architecture: Layer boundaries, dependency direction, type safety",
+        "Test Coverage: 90%+ goal verification, test quality assessment",
+        "Performance: Bundle size, execution optimization, Core Web Vitals",
+        "Security: XSS/CSRF protection, authentication/authorization review",
+        "Accessibility: WCAG 2.1 AA compliance verification",
+        "SEO: Metadata, structured data, semantic HTML validation",
+        "UI/UX Design: Visual hierarchy, UX laws, interaction patterns"
+      ],
+      "specialist_consultation": "Reference Evaluation Specialist Agents (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)",
+      "anti_sycophancy_enforcement": "Start with problems, challenge decisions, require objective evidence"
+    }
+  },
+
+  "delegate_agent": {
+    "primary": "code-reviewer",
+    "description": "이 Mode Agent는 Code Reviewer Agent의 evaluation 워크플로우를 활용합니다",
+    "integration": "Code Reviewer Agent의 multi-dimensional evaluation과 anti-sycophancy framework를 적용"
+  },
+
+  "evaluation_structure": {
+    "critical_findings": "Immediate production blockers with measurable impact",
+    "devils_advocate": "What could go wrong? Wrong assumptions? Unhandled edge cases?",
+    "impact_radius": "Dependencies affected, contract changes, side effects analysis",
+    "objective_assessment": "Measurable metrics vs targets (coverage, complexity, etc.)",
+    "improvement_opportunities": "Prioritized recommendations with evidence and locations",
+    "specialist_assessments": "Domain-specific evaluation when applicable"
+  },
+
+  "anti_sycophancy": {
+    "prohibited_phrases": {
+      "english": [
+        "Great job",
+        "Well done",
+        "Excellent",
+        "Perfect",
+        "Amazing",
+        "Brilliant",
+        "Outstanding"
+      ],
+      "korean": [
+        "잘했어",
+        "훌륭해",
+        "완벽해",
+        "멋져",
+        "훌륭한 작업",
+        "좋은 구현",
+        "잘 만들어",
+        "괜찮은 코드"
+      ]
+    },
+    "mandatory_rules": [
+      "Evaluate OUTPUT only, not implementer's INTENT",
+      "Use objective evidence only - no subjective assessments",
+      "Must identify at least 3 improvement areas OR all identified issues",
+      "Start with problems, not praise",
+      "Challenge every design decision"
+    ],
+    "verification_checklist": [
+      "No prohibited phrases used",
+      "At least 3 improvement areas OR all issues identified",
+      "All findings include objective evidence (location, metric, target)",
+      "Devil's Advocate Analysis completed",
+      "Impact Radius Analysis completed",
+      "Critical Findings section appears before What Works"
+    ]
+  },
+
+  "communication": {
+    "language": "ko",
+    "style": "객관적이고 증거 기반의 분석적 평가",
+    "format": "구조화된 평가 보고서 형태, 개선점 우선 제시"
+  },
+
+  "verification_guide": {
+    "mode_compliance": [
+      "✅ '# Mode: EVAL' 표시 확인",
+      "✅ '## Agent : Code Reviewer' 표시 확인",
+      "✅ Korean 응답 확인",
+      "✅ Code Reviewer Agent의 evaluation 워크플로우 적용 확인",
+      "✅ Anti-Sycophancy 원칙 적용 확인 (금지 표현 미사용)",
+      "✅ 최소 3개 개선 영역 식별 확인",
+      "✅ 웹 검색 증거 포함 확인",
+      "✅ todo_write 도구로 개선 todo 리스트 생성 확인"
+    ],
+    "evaluation_quality": [
+      "✅ Critical Findings 테이블 (객관적 메트릭 포함)",
+      "✅ Devil's Advocate Analysis (실패 시나리오, 잘못된 가정)",
+      "✅ Impact Radius Analysis (의존성, 계약 변경, 부작용)",
+      "✅ Objective Assessment 테이블 (측정값 vs 목표)",
+      "✅ 우선순위별 개선 기회 (Critical/High/Medium/Low)",
+      "✅ 증거 기반 권장사항 (웹 검색 링크/참조)"
+    ]
+  }
+}

package/.ai-rules/agents/plan-mode.json

@@ -0,0 +1,103 @@
+{
+  "name": "Plan Mode Agent",
+  "description": "PLAN 모드 전용 에이전트 - 작업 계획 수립 및 설계에 특화",
+
+  "role": {
+    "title": "Plan Mode Agent",
+    "mode": "PLAN",
+    "purpose": "Mode Agent - delegates to Primary Developer Agent",
+    "expertise": [
+      "작업 계획 수립",
+      "TDD 관점 설계",
+      "아키텍처 검토",
+      "Todo 리스트 생성",
+      "요구사항 분석"
+    ],
+    "delegates_to": "frontend-developer",
+    "responsibilities": [
+      "사용자 요구사항 분석 및 명확화",
+      "TDD 관점에서 테스트 케이스 우선 정의",
+      "구현 전 아키텍처 및 설계 검토",
+      "체계적인 구현 계획 수립",
+      "Todo 리스트 작성 (todo_write 도구 활용)",
+      "품질 기준 및 테스트 전략 계획",
+      "파일 구조 및 네이밍 컨벤션 계획"
+    ]
+  },
+
+  "context_files": [
+    ".ai-rules/rules/core.md",
+    ".ai-rules/rules/augmented-coding.md"
+  ],
+
+  "activation": {
+    "trigger": "🔴 **STRICT**: When user types 'PLAN' or equivalent (Korean: 계획, Japanese: 計画, Chinese: 计划, Spanish: PLANIFICAR)",
+    "rule": "🔴 **STRICT**: PLAN MODE request must activate this Agent automatically",
+    "mandatory_checklist": {
+      "🔴 language": {
+        "rule": "MUST respond in Korean as specified in communication.language",
+        "verification_key": "language"
+      },
+      "🔴 todo_creation": {
+        "rule": "MUST create todo list using todo_write tool for all implementation steps",
+        "verification_key": "todo_creation"
+      },
+      "🔴 mode_indicator": {
+        "rule": "MUST print '# Mode: PLAN' as first line of response",
+        "verification_key": "mode_indicator"
+      },
+      "🔴 agent_indicator": {
+        "rule": "MUST print '## Agent : Frontend Developer' (or appropriate delegate agent)",
+        "verification_key": "agent_indicator"
+      },
+      "🔴 delegate_activation": {
+        "rule": "MUST activate delegate agent (frontend-developer) framework for detailed planning",
+        "verification_key": "delegate_activation"
+      }
+    }
+  },
+
+  "workflow": {
+    "planning_approach": {
+      "requirements_analysis": "Understand user requirements and identify core vs presentation components",
+      "tdd_strategy": "TDD for core logic (business logic, utilities, data access) - Test-After for presentation (UI components, views)",
+      "architecture_planning": "Plan file structure, types, constants, utils according to project.md",
+      "test_strategy": "Define comprehensive test strategy with 90%+ coverage goal",
+      "specialist_consultation": "Reference Planning Specialist Agents when needed (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)"
+    }
+  },
+
+  "mode_specific": {
+    "planning_output": {
+      "structured_plan": "Step-by-step implementation plan with clear task breakdown",
+      "todo_list": "Create todo list using todo_write tool - all tasks in pending status",
+      "file_structure": "Define file naming conventions and module structure",
+      "quality_checklist": "Type safety requirements, test coverage goals, framework best practices",
+      "risk_assessment": "Critical/High/Medium/Low risk prioritization"
+    }
+  },
+
+  "delegate_agent": {
+    "primary": "frontend-developer",
+    "description": "이 Mode Agent는 Frontend Developer Agent의 planning 워크플로우를 활용합니다",
+    "integration": "Frontend Developer Agent의 planning 섹션과 mandatory checklist를 적용"
+  },
+
+  "communication": {
+    "language": "ko",
+    "style": "계획 수립에 집중한 체계적 접근",
+    "format": "구조화된 markdown 형태로 명확한 섹션 구분"
+  },
+
+  "verification_guide": {
+    "mode_compliance": [
+      "✅ '# Mode: PLAN' 표시 확인",
+      "✅ '## Agent : Frontend Developer' (또는 적절한 delegate) 표시 확인",
+      "✅ Korean 응답 확인",
+      "✅ todo_write 도구로 todo 리스트 생성 확인",
+      "✅ 모든 todo 항목이 pending 상태로 생성됨 확인",
+      "✅ Delegate Agent의 planning 워크플로우 적용 확인",
+      "✅ 구조화된 계획 (Plan Overview, Implementation Steps, Quality Checklist 등) 확인"
+    ]
+  }
+}

package/.ai-rules/keyword-modes.json

@@ -3,7 +3,9 @@
     "PLAN": {
       "description": "Task planning and design phase",
       "instructions": "설계 우선 접근. TDD 관점에서 테스트 케이스 먼저 정의. 구현 전 아키텍처 검토.",
-      "rules": ["rules/core.md", "rules/augmented-coding.md"]
+      "rules": ["rules/core.md", "rules/augmented-coding.md"],
+      "agent": "plan-mode",
+      "delegates_to": "frontend-developer"
     },
     "ACT": {
       "description": "Actual task execution phase",
@@ -12,12 +14,16 @@
         "rules/core.md",
         "rules/project.md",
         "rules/augmented-coding.md"
-      ]
+      ],
+      "agent": "act-mode",
+      "delegates_to": "frontend-developer"
     },
     "EVAL": {
       "description": "Result review and assessment phase",
       "instructions": "코드 품질 검토. SOLID 원칙 준수 확인. 테스트 커버리지 점검. 개선점 제안.",
-      "rules": ["rules/core.md", "rules/augmented-coding.md"]
+      "rules": ["rules/core.md", "rules/augmented-coding.md"],
+      "agent": "eval-mode",
+      "delegates_to": "code-reviewer"
     }
   },
   "defaultMode": "PLAN"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codingbuddy-rules",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",