codingbuddy-rules 2.0.0 → 2.1.0

package/.ai-rules/adapters/claude-code.md

@@ -175,9 +175,11 @@ CodingBuddy uses a layered agent hierarchy for different types of tasks:
 | Mode | Agents | Description |
 |------|--------|-------------|
 | **PLAN** | solution-architect, technical-planner | Design and planning tasks |
-| **ACT** | frontend-developer, backend-developer, devops-engineer, agent-architect | Implementation tasks |
+| **ACT** | tooling-engineer, frontend-developer, backend-developer, devops-engineer, agent-architect | Implementation tasks |
 | **EVAL** | code-reviewer | Code review and evaluation |
 
+> **Note**: `tooling-engineer` has highest priority for config/build tool tasks (tsconfig, eslint, vite.config, package.json, etc.)
+
 ### Tier 2: Specialist Agents
 
 Specialist agents can be invoked by any Primary Agent as needed:
@@ -195,9 +197,34 @@ Specialist agents can be invoked by any Primary Agent as needed:
 ### Agent Resolution
 
 1. **PLAN mode**: Always uses `solution-architect` or `technical-planner` based on prompt analysis
-2. **ACT mode**: Uses recommended agent from PLAN, or falls back to AI analysis
+2. **ACT mode**: Resolution priority:
+   1. Explicit agent request in prompt (e.g., "backend-developer로 작업해")
+   2. `recommended_agent` parameter (from PLAN mode recommendation)
+   3. Tooling pattern matching (config files, build tools → `tooling-engineer`)
+   4. Project configuration (`primaryAgent` setting)
+   5. Context inference (file extension/path)
+   6. Default: `frontend-developer`
 3. **EVAL mode**: Always uses `code-reviewer`
 
+### Using recommended_agent Parameter
+
+When transitioning from PLAN to ACT mode, pass the recommended agent:
+
+```typescript
+// After PLAN mode returns recommended_act_agent
+const planResult = await parse_mode({ prompt: "PLAN design auth API" });
+// planResult.recommended_act_agent = { agentName: "backend-developer", ... }
+
+// Pass to ACT mode for context preservation
+const actResult = await parse_mode({
+  prompt: "ACT implement the API",
+  recommended_agent: planResult.recommended_act_agent.agentName
+});
+// actResult.delegates_to = "backend-developer" (uses the recommendation)
+```
+
+This enables seamless agent context passing across PLAN → ACT workflow transitions.
+
 ## Activation Messages
 
 When agents or skills are activated, CodingBuddy displays activation messages for transparency:
@@ -257,3 +284,169 @@ AI assistants should display the `activation_message.formatted` field at the sta
 
 ...
 ```
+
+## Parallel Specialist Agents Execution
+
+CodingBuddy supports parallel execution of multiple specialist agents for comprehensive analysis.
+
+### When to Use Parallel Execution
+
+Parallel execution is recommended when `parse_mode` returns a `parallelAgentsRecommendation` field:
+
+| Mode | Default Specialists | Use Case |
+|------|---------------------|----------|
+| **PLAN** | architecture-specialist, test-strategy-specialist | Validate architecture and test approach |
+| **ACT** | code-quality-specialist, test-strategy-specialist | Verify implementation quality |
+| **EVAL** | security-specialist, accessibility-specialist, performance-specialist, code-quality-specialist | Comprehensive multi-dimensional review |
+
+### parallelAgentsRecommendation Response Field
+
+The `parse_mode` MCP tool returns this field to recommend parallel specialist execution:
+
+```json
+{
+  "mode": "EVAL",
+  "parallelAgentsRecommendation": {
+    "specialists": [
+      "security-specialist",
+      "accessibility-specialist",
+      "performance-specialist",
+      "code-quality-specialist"
+    ],
+    "hint": "Use Task tool with subagent_type=\"general-purpose\" and run_in_background=true for each specialist. Call prepare_parallel_agents MCP tool to get ready-to-use prompts."
+  }
+}
+```
+
+### Parallel Execution Workflow
+
+```
+parse_mode 호출
+     ↓
+parallelAgentsRecommendation 확인
+     ↓ (있으면)
+사용자에게 시작 메시지 표시
+     ↓
+prepare_parallel_agents MCP 호출
+     ↓
+반환된 각 agent.taskPrompt를 Task tool로 병렬 호출:
+  - subagent_type: "general-purpose"
+  - run_in_background: true
+  - prompt: agent.taskPrompt
+     ↓
+TaskOutput으로 결과 수집
+     ↓
+사용자에게 결과 종합하여 표시
+```
+
+### Code Example
+
+```typescript
+// Step 1: Parse mode returns parallelAgentsRecommendation
+const parseModeResult = await parse_mode({ prompt: "EVAL review auth implementation" });
+
+if (parseModeResult.parallelAgentsRecommendation) {
+  // Step 2: Display start message to user
+  console.log("🚀 Dispatching 4 specialist agents in parallel...");
+  console.log("   → 🔒 security-specialist");
+  console.log("   → ♿ accessibility-specialist");
+  console.log("   → ⚡ performance-specialist");
+  console.log("   → 📏 code-quality-specialist");
+
+  // Step 3: Prepare parallel agents
+  const preparedAgents = await prepare_parallel_agents({
+    mode: "EVAL",
+    specialists: parseModeResult.parallelAgentsRecommendation.specialists,
+    sharedContext: "Review authentication implementation",
+    targetFiles: ["src/auth/login.tsx"]
+  });
+
+  // Step 4: Execute in parallel using Task tool
+  const agentTasks = preparedAgents.agents.map(agent =>
+    Task({
+      subagent_type: "general-purpose",
+      prompt: agent.taskPrompt,
+      description: agent.description,
+      run_in_background: true,
+      model: "haiku" // Use haiku for efficiency
+    })
+  );
+
+  // Step 5: Collect results
+  const results = await Promise.all(agentTasks.map(task => TaskOutput(task.id)));
+
+  // Step 6: Display summary
+  console.log("📊 Specialist Analysis Complete:");
+  results.forEach(result => console.log(result.summary));
+}
+```
+
+### Visibility Pattern
+
+When executing parallel specialists, display clear status messages:
+
+**Start Message:**
+```
+🚀 Dispatching N specialist agents in parallel...
+   → 🔒 security-specialist
+   → ♿ accessibility-specialist
+   → ⚡ performance-specialist
+   → 📏 code-quality-specialist
+```
+
+**Completion Message:**
+```
+📊 Specialist Analysis Complete:
+
+🔒 Security Specialist:
+   [findings summary]
+
+♿ Accessibility Specialist:
+   [findings summary]
+
+⚡ Performance Specialist:
+   [findings summary]
+
+📏 Code Quality Specialist:
+   [findings summary]
+```
+
+### Specialist Icons
+
+| Icon | Specialist |
+|------|------------|
+| 🔒 | security-specialist |
+| ♿ | accessibility-specialist |
+| ⚡ | performance-specialist |
+| 📏 | code-quality-specialist |
+| 🧪 | test-strategy-specialist |
+| 🏛️ | architecture-specialist |
+| 📚 | documentation-specialist |
+| 🔍 | seo-specialist |
+| 🎨 | design-system-specialist |
+
+### Handling Failures
+
+When `prepare_parallel_agents` returns `failedAgents`:
+
+```
+⚠️ Some agents failed to load:
+   ✗ performance-specialist: Profile not found
+
+Continuing with 3/4 agents...
+```
+
+**Strategy:**
+- Continue with successfully loaded agents
+- Report failures clearly to user
+- Document which agents couldn't be loaded in final report
+
+### Specialist Activation Scope
+
+Each workflow mode activates different specialist agents:
+
+- **PLAN mode**: Architecture and test strategy specialists validate design
+- **ACT mode**: Code quality and test strategy specialists verify implementation
+- **EVAL mode**: Security, accessibility, performance, and code quality specialists provide comprehensive review
+
+**Important:** Specialists from one mode do NOT carry over to the next mode. Each mode has its own recommended specialist set.

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

@@ -1,151 +1,173 @@
 # Cursor Integration Guide
 
-This guide explains how to use the common AI rules (`.ai-rules/`) in Cursor.
+Guide for using codingbuddy with Cursor.
 
 ## Overview
 
-Cursor continues to use its native `.cursor/` directory structure while referencing the common rules from `.ai-rules/`.
+codingbuddy integrates with Cursor in two ways:
 
-## Integration Method
+1. **AGENTS.md** - Industry standard format compatible with all AI tools
+2. **.cursor/rules/*.mdc** - Cursor-specific optimization (glob-based auto-activation)
 
-### 1. Reference Common Rules
+## Two Usage Contexts
 
-Create `.cursor/rules/imports.mdc` to reference common rules:
+### End Users (Your Project)
 
-```markdown
+End users access rules **only through MCP tools**. No local rule files needed.
+
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy"]
+    }
+  }
+}
+```
+
+Optional: Create `.cursor/rules/codingbuddy.mdc` for basic integration:
+
+```yaml
 ---
-description: Common AI Rules Import
+description: codingbuddy integration
 globs:
 alwaysApply: true
 ---
 
-# Common Rules
-
-This project uses shared rules from `.ai-rules/` directory for all AI assistants.
-
-## 📚 Core Rules
-See [../../.ai-rules/rules/core.md](../../.ai-rules/rules/core.md) for:
-- PLAN/ACT/EVAL workflow modes
-- Agent activation rules
-- Communication guidelines
-
-## 🏗️ Project Setup
-See [../../.ai-rules/rules/project.md](../../.ai-rules/rules/project.md) for:
-- Tech stack and dependencies
-- Project structure and architecture
-- Development rules and conventions
-- Domain knowledge and business context
-
-## 🎯 Augmented Coding Principles
-See [../../.ai-rules/rules/augmented-coding.md](../../.ai-rules/rules/augmented-coding.md) for:
-- TDD cycle (Red → Green → Refactor)
-- Code quality standards (SOLID, DRY)
-- Testing best practices
-- Commit discipline
-
-## 🤖 Specialist Agents
-See [../../.ai-rules/agents/README.md](../../.ai-rules/agents/README.md) for available specialist agents:
-- Frontend Developer, Code Reviewer
-- Architecture, Test Strategy, Performance, Security
-- Accessibility, SEO, Design System, Documentation
-- Code Quality, DevOps Engineer
+When PLAN, ACT, EVAL keywords detected → call `parse_mode` MCP tool
 ```
 
-### 2. Keep Cursor-Specific Features
+### Monorepo Contributors
 
-Maintain `.cursor/rules/cursor-specific.mdc` for Cursor-only features:
+Contributors to the codingbuddy repository can use direct file references:
 
-```markdown
+```
+Project Root/
+├── AGENTS.md                    # Cross-platform entry point
+├── .cursor/rules/
+│   ├── imports.mdc              # Common rules (alwaysApply: true)
+│   ├── auto-agent.mdc           # File pattern-based Agent auto-activation
+│   └── custom.mdc               # Personal settings (Git ignored)
+└── packages/rules/.ai-rules/    # Single Source of Truth
+```
+
+## DRY Principle
+
+**Single Source of Truth**: `packages/rules/.ai-rules/`
+
+- All Agent definitions, rules, skills managed only in `.ai-rules/`
+- AGENTS.md and .mdc files act as **pointers only**
+- No duplication, only references
+
+## Configuration Files
+
+### imports.mdc (alwaysApply)
+
+Core rules automatically applied to all conversations:
+
+```yaml
 ---
-description: Cursor-specific configurations
+description: codingbuddy common rules
 globs:
 alwaysApply: true
 ---
 
-# Cursor-Specific Features
+# Core principles only (details in .ai-rules/)
+```
 
-## File Globbing
+### auto-agent.mdc (glob-based)
 
-[Add Cursor-specific glob patterns here]
+Automatically provides appropriate Agent context based on file patterns:
 
-## Agent Tool Integration
+```yaml
+---
+description: Agent auto-activation
+globs:
+  - "**/*.tsx"
+  - "**/*.ts"
+  - "**/*.go"
+alwaysApply: false
+---
 
-[Add Cursor-specific todo_write tool usage]
+# File pattern → Agent mapping table
 ```
 
-## Current Structure
+## Usage
+
+### Mode Keywords
 
 ```
-.cursor/
-├── agents/              # Keep for Cursor compatibility
-├── rules/
-│   ├── core.mdc        # Keep existing (can add reference to .ai-rules)
-│   ├── project.mdc     # Keep existing (can add reference to .ai-rules)
-│   ├── augmented-coding.mdc  # Keep existing
-│   ├── imports.mdc     # NEW: References to .ai-rules
-│   └── cursor-specific.mdc   # NEW: Cursor-only features
-└── config.json         # Cursor configuration
-
-.ai-rules/              # Common rules for all AI tools
-├── rules/
-│   ├── core.md
-│   ├── project.md
-│   └── augmented-coding.md
-├── agents/
-│   └── *.json
-└── adapters/
-    └── cursor.md (this file)
+PLAN Design user authentication feature
 ```
 
-## Usage
+→ `parse_mode` MCP tool is called, loading appropriate Agent and rules
 
-### In Cursor Chat
+### Auto-Activation on File Edit
 
-Reference rules directly:
-```
-@.ai-rules/rules/core.md
-@.ai-rules/agents/frontend-developer.json
+Open `.tsx` file → `auto-agent.mdc` auto-applies → frontend-developer Agent recommended
 
-Create a new feature following our common workflow
-```
+### Specialist Usage
 
-### In Cursor Composer
-
-The `.cursor/rules/imports.mdc` with `alwaysApply: true` will automatically apply common rules to all Composer sessions.
+```
+EVAL Review from security perspective
+```
 
-## Benefits
+→ security-specialist activated
 
-- ✅ Seamless integration with existing Cursor setup
-- ✅ Access to common rules shared across all AI tools
-- ✅ Cursor-specific features (globs, alwaysApply) still work
-- ✅ Easy to update: change `.ai-rules/` once, all tools benefit
+## MCP Tools
 
-## Maintenance
+Available codingbuddy MCP tools in Cursor:
 
-When updating rules:
-1. Update `.ai-rules/rules/*.md` for changes affecting all AI tools
-2. Update `.cursor/rules/*.mdc` only for Cursor-specific changes
-3. Keep both in sync for best experience
+| Tool | Purpose |
+|------|---------|
+| `parse_mode` | Parse mode keywords + load Agent/rules |
+| `get_agent_details` | Get specific Agent details |
+| `get_project_config` | Get project configuration |
+| `recommend_skills` | Recommend skills based on prompt |
+| `prepare_parallel_agents` | Prepare parallel Agent execution |
 
 ## Skills
 
 ### Using Skills in Cursor
 
-Reference skills in your prompts using file inclusion:
+Load skills via file reference (monorepo only):
 
 ```
-@.ai-rules/skills/test-driven-development/SKILL.md
+@packages/rules/.ai-rules/skills/test-driven-development/SKILL.md
 ```
 
-Or manually include skill content in `.cursorrules`.
+For end users, use `recommend_skills` MCP tool instead.
 
 ### Available Skills
 
-- `.ai-rules/skills/brainstorming/SKILL.md`
-- `.ai-rules/skills/test-driven-development/SKILL.md`
-- `.ai-rules/skills/systematic-debugging/SKILL.md`
-- `.ai-rules/skills/writing-plans/SKILL.md`
-- `.ai-rules/skills/executing-plans/SKILL.md`
-- `.ai-rules/skills/subagent-driven-development/SKILL.md`
-- `.ai-rules/skills/dispatching-parallel-agents/SKILL.md`
-- `.ai-rules/skills/frontend-design/SKILL.md`
+- `brainstorming/SKILL.md` - Idea → Design
+- `test-driven-development/SKILL.md` - TDD workflow
+- `systematic-debugging/SKILL.md` - Systematic debugging
+- `writing-plans/SKILL.md` - Implementation plan writing
+- `executing-plans/SKILL.md` - Plan execution
+- `subagent-driven-development/SKILL.md` - Subagent development
+- `dispatching-parallel-agents/SKILL.md` - Parallel Agent dispatch
+- `frontend-design/SKILL.md` - Frontend design
+
+## AGENTS.md
+
+Industry standard format compatible with all AI tools (Cursor, Claude Code, Codex, etc.):
+
+```markdown
+# AGENTS.md
+
+This project uses codingbuddy MCP server to manage AI Agents.
+
+## Quick Start
+...
+```
+
+See `AGENTS.md` in project root for details.
+
+## Reference
+
+- [AGENTS.md Official Spec](https://agents.md)
+- [Cursor Rules Documentation](https://cursor.com/docs/context/rules)
+- [codingbuddy MCP API](../../docs/api.md)

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

@@ -28,6 +28,8 @@ AI Agent definitions for specialized development roles.
 | **Implementation Planning** | Technical Planner | `technical-planner.json` |
 | **React/Next.js Development** | Frontend Developer | `frontend-developer.json` |
 | **Backend API Development** | Backend Developer | `backend-developer.json` |
+| **Database/Schema Design** | Data Engineer | `data-engineer.json` |
+| **Mobile App Development** | Mobile Developer | `mobile-developer.json` |
 | **Code Review (EVAL)** | Code Reviewer | `code-reviewer.json` |
 | **Architecture Design** | Architecture Specialist | `architecture-specialist.json` |
 | **Test Strategy** | Test Strategy Specialist | `test-strategy-specialist.json` |
@@ -36,9 +38,11 @@ AI Agent definitions for specialized development roles.
 | **Accessibility Review** | Accessibility Specialist | `accessibility-specialist.json` |
 | **SEO Optimization** | SEO Specialist | `seo-specialist.json` |
 | **UI/UX Design** | UI/UX Designer | `ui-ux-designer.json` |
+| **Internationalization** | i18n Specialist | `i18n-specialist.json` |
 | **Documentation** | Documentation Specialist | `documentation-specialist.json` |
 | **Code Quality** | Code Quality Specialist | `code-quality-specialist.json` |
 | **Infrastructure/Deployment** | DevOps Engineer | `devops-engineer.json` |
+| **Config/Build Tools** | Tooling Engineer | `tooling-engineer.json` |
 | **Agent Management** | Agent Architect | `agent-architect.json` |
 
 ### Agent Summary
@@ -49,6 +53,8 @@ AI Agent definitions for specialized development roles.
 | Technical Planner | Low-level implementation planning with TDD and bite-sized tasks |
 | Frontend Developer | TDD-based frontend development with React/Next.js |
 | Backend Developer | Multi-stack backend API development (Node, Python, Go, Java, Rust) |
+| Data Engineer | Database schema design, migrations, query optimization, analytics |
+| Mobile Developer | Cross-platform (React Native, Flutter) and native (iOS, Android) development |
 | Code Reviewer | Auto-activated in EVAL mode, multi-dimensional code quality assessment |
 | Architecture Specialist | Layer boundaries, dependency direction, Clean Architecture |
 | Test Strategy Specialist | TDD strategy, test coverage, test quality |
@@ -57,9 +63,11 @@ AI Agent definitions for specialized development roles.
 | Accessibility Specialist | WCAG 2.1 AA, semantic HTML, screen reader support |
 | SEO Specialist | Metadata, JSON-LD, Open Graph |
 | UI/UX Designer | Visual hierarchy, UX laws, interaction patterns |
+| i18n Specialist | Internationalization, translation key structure, RTL support |
 | Documentation Specialist | Code comments, JSDoc, documentation quality assessment |
 | Code Quality Specialist | SOLID, DRY, complexity analysis |
 | DevOps Engineer | Docker, monitoring, deployment optimization |
+| Tooling Engineer | Project configuration, build tools, dev environment setup |
 | Agent Architect | AI agent design, validation, checklist auditing |
 
 ---
@@ -108,6 +116,7 @@ as agent-architect, design new agent
 
 | Agent | role.type | Activation Condition |
 |-------|-----------|---------------------|
+| Tooling Engineer | `primary` | Config files, build tools, package management (highest priority) |
 | Frontend Developer | `primary` | Default for ACT mode, React/Next.js projects |
 | Backend Developer | `primary` | Backend file context (.go, .py, .java, .rs) |
 | Agent Architect | `primary` | Agent-related work requests |
@@ -143,6 +152,7 @@ Mode Agents (Workflow Orchestrators)
 └── eval-mode      → delegates to → code-reviewer (always)
 
 Primary Agents (Implementation Experts) - role.type: "primary"
+├── tooling-engineer       # Config/build tools specialist (highest priority)
 ├── frontend-developer     # React/Next.js expertise (default)
 ├── backend-developer      # Multi-language backend expertise
 ├── agent-architect        # AI agent framework expertise
@@ -475,6 +485,51 @@ Unified specialist agents organized by domain:
 
 ---
 
+### Tooling Engineer (`tooling-engineer.json`)
+
+> **Note**: This is a **Primary Agent** for ACT mode, specializing in project configuration and build tools. Has highest priority for config/tooling related tasks.
+
+**Expertise:**
+
+- Project Configuration (codingbuddy.config.js, .env)
+- TypeScript Configuration (tsconfig.json, paths)
+- Linting & Formatting (ESLint, Prettier, Stylelint)
+- Build Tools (Vite, Webpack, Next.js config, Rollup)
+- Package Management (package.json, yarn workspaces, dependencies)
+- MCP Tools & IDE Integration
+- Development Environment Setup
+
+**Development Philosophy:**
+
+- **Schema-First**: Configuration changes must maintain valid schema structure
+- **Backward-Compatible**: Changes must not break existing configurations or builds
+- **Documented**: Non-obvious configuration options must have inline comments
+- **Validated**: All changes validated through lint, typecheck, and build
+
+**Responsibilities:**
+
+- Configure and optimize project settings
+- Set up and maintain build tool configurations
+- Manage linter and formatter rules
+- Handle package dependencies and workspace configuration
+- Configure TypeScript compiler options
+- Set up development environment and IDE settings
+- Integrate MCP tools with development workflow
+
+**Workflow:**
+
+- **Config Modification**: Incremental change with validation
+- **Tool Setup**: Best practices implementation with project pattern alignment
+- **Dependency Management**: Safe updates with compatibility checking
+
+**Activation Patterns:**
+
+- Config files: `codingbuddy.config`, `tsconfig`, `eslint`, `prettier`, `vite.config`, `next.config`
+- Korean: "설정 파일", "빌드 설정", "패키지 관리", "린터 설정"
+- English: "config file", "build config", "package management"
+
+---
+
 ### Agent Architect (`agent-architect.json`)
 
 > **Note**: This is a **Primary Agent** for managing AI agent configurations, schemas, and validation.
@@ -853,6 +908,7 @@ All agent files are located directly in `.ai-rules/agents/` directory without su
 .ai-rules/agents/
 ├── solution-architect.json          # Primary Agent for PLAN mode (architecture)
 ├── technical-planner.json           # Primary Agent for PLAN mode (implementation)
+├── tooling-engineer.json            # Primary Agent for ACT mode (config/build tools)
 ├── frontend-developer.json          # Primary Agent for ACT mode (default)
 ├── backend-developer.json           # Primary Agent for ACT mode (backend)
 ├── agent-architect.json             # Primary Agent for agent management